Fix more markup

2024-11-23 12:24:19 +00:00 · 2012-04-13 21:57:31 +02:00 · 2012-04-13 21:57:31 +02:00 · 6e1f913281
commit 6e1f913281
parent db3b4fa44e
3 changed files with 74 additions and 50 deletions
--- a/doc.lua
+++ b/doc.lua
@ -126,7 +126,7 @@ end]===]
 		long = [===[
 		Calls the corresponding function on the current gamestate (see [^#{{MODULE}}-callbacks callbacks]).

-		Only needed when not using registerEvents().]===],
+		Only needed when not using {#registerEvents()}.]===],
 		params = {
 			{"mixed", "...", "Arguments to pass to the corresponding [^#{{MODULE}}-callbacks callback]."},
 		},
@ -151,7 +151,7 @@ end]===],
 	Function { name = "registerEvents",
 		short = "Automatically do all of the above when needed.",
 		long = [===[
-		Register all love callbacks to call Gamestate.update(), Gamestate.draw(), etc. automatically.
+		Register love callbacks to call {#Gamestate.update()}, {#Gamestate.draw()}, etc. automatically.

 		This is by done by overwriting the love callbacks, e.g.:
 		[%local old_update = love.update
@ -162,12 +162,19 @@ end]

 		{!Note:} Only works when called in {#love.load()} or any other function that is executed
 after the whole file is loaded.]===],
-		params = {},
+		params = {
+			{'table', 'callbacks', 'Names of the callbacks to register. If omitted, register all callbacks.', optional = true},
+		},
 		returns = {},
-		example = [===[function love.load()
+		example = {
+			[===[function love.load()
    Gamestate.registerEvents()
    Gamestate.switch(menu)
-end]===],
+end]===], [===[function love.load()
+    Gamestate.registerEvents{'draw', 'update', 'quit'}
+    Gamestate.switch(menu)
+end]===]
+		}
 	},
 }

@ -187,7 +194,7 @@ Module { name = "hump.timer",
 		short = "Add a timed function.",
 		long = [===[
 		Add a timed function. The function will be executed after {#delay} seconds
-		have elapsed, given that update() is called every frame.
+		have elapsed, given that {#update(dt)} is called every frame.

 		Note that there is no guarantee that the delay will not be exceeded, it is
 		only guaranteed that the function will not be executed {*before} the delay
@ -221,7 +228,7 @@ Timer.add(1, function(func) print("foo") Timer.add(1, func) end)]===]
 		Add a function that will be called {#count} times every {#delay} seconds.

 		If {#count} is omitted, the function will be called until it returns {#false}
-		or clear() is called.]===],
+		or {#clear()} is called.]===],
 		params = {
 			{"number", "delay", "Number of seconds between two consecutive function calls."},
 			{"function", "func", "The function to be called periodically."},
@ -245,9 +252,9 @@ end)]===],
 		short = "Cancel a scheduled function.",
 		long = [===[Prevent a timer from being executed in the future.

-		{*Always} use the function handle returned by add()/addPeriodic() to cancel a timer.
+		{*Always} use the function handle returned by {#add()}/{#addPeriodic()} to cancel a timer.

-		{*Never} use this in another timer.]===],
+		{*Never} use this inside another timer.]===],
 		params = {
 			{"function", "func", "The function to be canceled."},
 		},
@ -272,7 +279,7 @@ Timer.cancel(handle) -- NOT: Timer.cancel(tick)]===]

 	Function { name = "update",
 		short = "Update timed functions.",
-		long = "Update timers and execute functions if the deadline is reached. Use this in love.update(dt).",
+		long = "Update timers and execute functions if the deadline is reached. Use this in {#love.update(dt)}.",
 		params = {
 			{"number", "dt", "Time that has passed since the last update()."},
 		},
@ -324,11 +331,11 @@ end]===],
 		Create a wrapper for an oscillating function, which is basically a looping
 		interpolating function.

-		The function prototypes are the same as with Interpolator():
+		The function prototypes are the same as with {#Interpolator()}:
 		[%function wrapper(dt, ...)]
 		[%function oscillator(fraction, ...)]

-		As with Interpolator, the wrapper will return whatever {#oscillator()} returns.]===],
+		As with {#Interpolator}, the wrapper will return whatever {#oscillator()} returns.]===],
 		params = {
 			{"number", "length", "Length of one interpolation period."},
 			{"function", "func", "Oscillating function."},
@ -587,8 +594,8 @@ spawner.direction:rotate_inplace(dt)]===],
 	Function { name = "vector:perpendicular",
 		short = "Get perpendicular vector.",
 		long = [===[
-		Quick rotation by 90°. Creates a new vector. The same as (but faster):
-		[%vec:rotate(math.pi/2)]]===],
+		Quick rotation by 90&deg;. Creates a new vector. The same (but faster) as
+		{#vec:rotate(math.pi/2)}]===],
 		params = {},
 		returns = {
 			{"vector", "A vector perpendicular to the input vector"}
@ -676,7 +683,7 @@ Module { name = "hump.vector-light",
 			"Product of a vector and a scalar.",
 			"Product of a vector and the inverse of a scalar.",
 		},
-		long = "Computes {#x*s, y*s} and {#x/s, y/s}. The order of arguments is chosen so that you can chain multiple operations (see example).",
+		long = "Computes {#x*s,y*s} and {#x/s,y/s} respectively. The order of arguments is chosen so that it's possible to chain multiple operations (see example).",
 		params = {
 			{"number", "s", "The scalar."},
 			{"numbers", "x,y", "The vector."},
@ -695,7 +702,7 @@ Module { name = "hump.vector-light",
 			"Sum of two vectors.",
 			"Difference of two vectors.",
 		},
-		long = "Computes the sum/difference of vectors. Same as {#x1+x2, y1+y2} or {#x1-x2, y1-y2} respectively. Meant to be used in conjunction with other functions.",
+		long = "Computes the sum/difference of vectors. Same as {#x1+x2,y1+y2} and {#x1-x2,y1-y2} respectively. Meant to be used in conjunction with other functions.",
 		params = {
 			{"numbers", "x1,y1", "First vector."},
 			{"numbers", "x2,y2", "Second vector."},
@ -712,7 +719,7 @@ Module { name = "hump.vector-light",
 	Function { name = "permul",
 		short = "Per element multiplication.",
 		long = [===[
-		Multiplies vectors coordinate wise, i.e. {#x1*x2, y1*y2)}.]===],
+		Multiplies vectors coordinate wise, i.e. {#x1*x2,y1*y2}.]===],
 		params = {
 			{"numbers", "x1,y1", "First vector."},
 			{"numbers", "x2,y2", "Second vector."},
@ -725,7 +732,7 @@ Module { name = "hump.vector-light",

 	Function { name = "dot",
 		short = "[^http://en.wikipedia.org/wiki/Dot_product Dot product]",
-		long = "Computes the [^http://en.wikipedia.org/wiki/Dot_product dot product] of two vectors, {#x1*x2 + y1*y2}.",
+		long = "Computes the [^http://en.wikipedia.org/wiki/Dot_product dot product] of two vectors, {#x1*x2+y1*y2}.",
 		params = {
 			{"numbers", "x1,y1", "First vector."},
 			{"numbers", "x2,y2", "Second vector."},
@ -738,7 +745,7 @@ Module { name = "hump.vector-light",

 	Function { name = {"det", "cross"},
 		short = { "Cross product", "Cross product", },
-		long = "Computes the cross product/determinant of two vectors, {#x1*y2 - y1*x2}.",
+		long = "Computes the cross product/determinant of two vectors, {#x1*y2-y1*x2}.",
 		params = {
 			{"numbers", "x1,y1", "First vector."},
 			{"numbers", "x2,y2", "Second vector."},
@ -856,7 +863,7 @@ end]===],

 	Function { name = "perpendicular",
 		short = "Get perpendicular vector.",
-		long = "Quick rotation by 90°. The same as (but faster) [%vector.rotate(math.pi/2, x,y)]",
+		long = "Quick rotation by 90&deg;. The same (but faster) as {#vector.rotate(math.pi/2, x,y)}",
 		params = {
 			{"numbers", "x,y", "The vector."},
 		},
@ -921,12 +928,12 @@ Module { name = "hump.class",
 [===[
 Class = require 'hump.class' -- `Class' is now a shortcut to new()

-- define class with implicit name  'Feline'
+-- define unnamed class
 Feline = Class{function(self, size, weight)
    self.size = size
    self.weight = weight
 end}
-print(Feline) -- prints 'Feline'
+print(Feline) -- prints '<unnamed class>

 -- define class method
 function Feline:stats()
@ -949,7 +956,7 @@ Feline = Class{name = "Feline", function(self, size, weight)
 end}

 garfield = Feline(.7, 45)
-print(Feline, garfield) -- prints 'Feline	<instance of Feline>'
+print(Feline, garfield) -- prints '<unnamed class>	<instance of <unnamed class>>'
 ]===],
 [===[
 Class = require 'hump.class'
@ -1150,8 +1157,8 @@ result:show()   -- prints "A:    4"
 result:foo()    -- error: method does not exist]

 		Note that while you can define the {#__index} metamethod of the class, this
-		is not a good idea: It will break the class. To add a custom __index
-		metamethod without breaking the class system, you have to use rawget().
+		is not a good idea: It will break the class. To add a custom {#__index}
+		metamethod without breaking the class system, you have to use {#rawget()}.
 		But beware that this won't affect subclasses:
 		[%Class = require 'hump.class'

@ -1353,7 +1360,7 @@ love.graphics.line(x, y, love.mouse.getPosition())

 	Function { name = "camera:mousepos",
 		short = "Get mouse position in world coordinates.",
-		long = "Shortcut to {#camera:worldCoords(vector(love.mouse.getPosition()))}.",
+		long = "Shortcut to {#camera:worldCoords(love.mouse.getPosition())}.",
 		params = {},
 		returns = {
 			{"numbers", "Mouse position in world coordinates."},
--- a/index.html
+++ b/index.html
--- a/makedoc.lua
+++ b/makedoc.lua
@ -175,11 +175,26 @@ function Function(M)
 	end
 	short = table.concat(short)

-	local args = {}
-	for _,p in ipairs(M.params) do
-		args[#args+1] = p[2]
+	local args
+	if #M.params == 0 then
+		args = '()'
+	elseif M.params.table_argument then
+		args = {}
+		for i,p in ipairs(M.params) do
+			if p.name then
+				args[i] = p.name..' = '.. p[2]
+			else
+				args[i] = p[2]
+			end
+		end
+		args = '{'..table.concat(args, ', ')..'}'
+	else
+		args = {}
+		for i,p in ipairs(M.params) do
+			args[i] = p[2]
+		end
+		args = '('..table.concat(args, ', ')..')'
 	end
-	args = #args>0 and table.concat(args, ', ') or ''

 	local long = {}
 	local function F(s, ...) long[#long+1] = select('#', ...) > 0 and s:format(...) or s end
@ -188,7 +203,7 @@ function Function(M)
 	for i=1,#M.name do F('<a name="{{MODULE}}-%s" id="{{MODULE}}-%s"></a>', M.name[i], M.name[i]) end
 	F('<div class="ref-block">')
 	for i=1,#M.name do
-		F('<h4>function <span class="name">%s</span><span class="arglist">(%s)</span><a class="top" href="#{{MODULE}}">^ top</a></h4>', M.name[i], args) -- section block>
+		F('<h4>function <span class="name">%s</span><span class="arglist">%s</span><a class="top" href="#{{MODULE}}">^ top</a></h4>', M.name[i], args) -- section block>
 	end

 	-- description
@ -198,7 +213,7 @@ function Function(M)
 	F('<div class="arguments">Parameters:<dl>')
 	if #M.params == 0 then F('<dt>None</dt>') end
 	for _,p in ipairs(M.params) do
-		F('<dt>%s <code>%s</code></dt><dd>%s</dd>', p[1], p[2], markup(p[3]):sub(4,-5))
+		F('<dt>%s <code>%s</code>%s</dt><dd>%s</dd>', p[1], p[2], p.optional and ' (optional)' or '', markup(p[3]):sub(4,-5))
 	end
 	F('</dl></div>')

@ -232,10 +247,9 @@ end

 dofile(...) -- magic

-
 -- ASSEMBLE DOCUMENTATION MARKUP
 io.write([[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><title>hump - L&Ouml;VE Helper Utilities for More Productivity</title><link rel="stylesheet" type="text/css" href="style.css" /><link rel="stylesheet" type="text/css" href="highlight.css" /><script type="text/javascript" src="highlight.pack.js"></script><script type="text/javascript">window.onload = function() {var examples = document.getElementsByTagName("code");for (i = 0; i < examples.length; ++i) {if (examples[i].className == "lua")hljs.highlightBlock(examples[i], "    ");}};</script></head><body><a name="top" id="top"></a><div id="header"><h1><a href="http://github.com/vrld/hump">hump</a><span class="small"> Helper Utilities for More Productivity</span></h1><ul id="main-nav"><li><a href="#intro">Introduction</a></li><li><a href="#doc">Documenation</a></li><li><a href="#license">License</a></li><li><a href="#download">Download</a></li></ul><h2>&nbsp;</h2></div><a name="intro" id="intro"></a><div class="outer-block"><h3>Introduction<a class="top" href="#top">^ top</a></h3><div class="preamble"><p><em>Helper Utilities for a Multitude of Problems</em> is a set of lightweight helpers for the <strong>awesome</strong> <a href="http://love2d.org/">L&Ouml;VE</a> Engine.</p><p>It features<ul><li><em>gamestate.lua</em>: a gamestate system.</li><li><em>timer.lua</em>: timed function calling and interpolating functions,</li><li><em>vector.lua</em>: a mature vector type,</li><li><em>vector-light.lua</em>: lightweight vector math,</li><li><em>class.lua</em>: a simple and easy class system,</li><li><em>camera.lua</em>: a move-, zoom- and rotatable camera and</li><li><em>ringbuffer.lua</em>: a circular container.</li></ul></p><p><em>hump</em> differs from other libraries in that every component is independent of the remaining ones (apart from camera.lua, which does depends on vector.lua). <em>hump</em>'s footprint is very small and thus should fit nicely into your projects.</p></div></div><a name="doc"></a><div class="outer-block"><h3>Documentation<a class="top" href="#top">^ top</a></h3><div class="preamble">]])
 io.write('<dl>'..table.concat(DOC.short):gsub('Ö', '&Ouml;')..'</dl>')
 io.write([[</div></div>]])
-io.write(table.concat(DOC.long):gsub('Ö', '&Ouml;'))
+io.write(''..table.concat(DOC.long):gsub('Ö', '&Ouml;'))
 io.write[[<a name="license" id="license"></a><div class="outer-block"><h3>License<a class="top" href="#top">^ top</a></h3><div class="preamble"><p>Yay, <em>free software</em>:</p><blockquote><p>Copyright (c) 2010 Matthias Richter</p><p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p><p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p><p>Except as contained in this notice, the name(s) of the above copyright holders shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization.</p><p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p></blockquote></div></div><a name="download" id="download"></a><div class="outer-block"><h3>Download<a class="top" href="#top">^ top</a></h3><div class="preamble"><p>You can view and download the individual modules on github: <a href="http://github.com/vrld/hump">vrld/hump</a>. You may also download the whole packed sourcecode either in <a href="http://github.com/vrld/hump/zipball/master">zip</a> or <a href="http://github.com/vrld/hump/tarball/master">tar</a> formats.</p><p>You can clone the project with <a href="http://git-scm.com">Git</a> by running: <pre>git clone git://github.com/vrld/hump</pre> Once done, you can check for updates by running <pre>git pull</pre></p></div></div></body>]]