Commit e38a1b140209b8adc9dde55f9c2178b2acdefcba - lua-ldoc

Better section naming, some hints for C code JonasT 10 years ago

1 changed file(s) with 16 addition(s) and 4 deletion(s). Raw diff Collapse all Expand all

+16

-4

doc/doc.md less more

75	75
76	76	The first important tag to know is the module tag:
77	77
78		#### The module tag, naming and describing your API module
	78	#### Modules: naming and describing your API module
79	79
80	80	The first thing in your API module should be a name and a description.
81	81	This is how a module is commonly done in Lua 5.2 with a @module tag at the top

96	96
97	97	This sets up a module named 'test' with the description 'a test module'.
98	98
99		#### Describing functions with tags:
	99	#### Functions:
100	100
101	101	The next thing to describe are the functions your module has.
102	102	This is a simple example of a documented function:

109	109	....
110	110	end
111	111
	112	You can also give the function name itself as an explicit tag,
	113	which is especially useful when documenting a Lua api exported by C code:
	114	/// A C function which is exported to Lua with another name,
	115	// because the ways of C can be mysterious!
	116	// @function our_nice_function
	117	int _some_function_for_lua(lua_State* l) {
	118	....
	119	}
	120
112	121	The tags basically add all the detail that cannot be derived from the source code
113	122	automatically.
114	123
115		#### Most common tags: param, return, tparam, treturn
	124	#### Function parameters and return values
116	125
117	126	Common tags are the 'param' tag which takes a parameter name followed by a parameter
118	127	description separated by a space, and the 'return' tag which is simply followed by

150	159	...
151	160	Of course there is also the 'module' tag which you have already seen.
152	161
153		#### Describing tables and constants: field, table
	162	#### Tables and constant values (fields)
154	163
155	164	Modules can of course export tables and other values. The classic way to document a table
156	165	looks like this:

196	205	function my_function()
197	206	...
198	207	end
	208	As mentioned before, this is often especially useful in C where things
	209	may look different in the C code than they will in the final Lua api which
	210	you want to document.
199	211
200	212	### Doing modules the Lua 5.1 way
201	213