| 词条 | Module:LuaDoc/doc |
| 释义 |
UsageUsual call for documentation of a single module, like a replacement for the usual documentation page, would be like this In the actual code there will be specially formatted comments. All comments acted upon by this use a single line comment followed by an at sign (@) and a tag name. (Is there any reason why we should use other kinds of comments? They are useful for commenting out blocks? How to describe local functions? Should inline docs be used, those can be supported by wikitext?) Note that all text is processed as wikitext, and it is possible to link internally and externally as seems fit. This also creates some problems as part of the text will have spaces or page breaks in odd places. An summary-line is prefixed by three (3) hyphens (dashes), and double as a marker for the place where the code is to be divided into chunks. The stuff in each chunk is precessed separately. The summary will be marked as such, and it will be possible to use it as a fragment identifier. A tag is prefixed by two (2) hyphens (dashes), optional spaces, a single at-sign (@) and a tag name. The following text can be further split and given special markup. A single line comment following a summary or tag will be joined with the preceding line. If the line contains text it will be joined with a dividing space, if it is empty it will add a newline. The newline can be further processed and given special markup. Recognised tags can be removed from the document flow or left in place, as seems fit for the processed chunk of text. Those removed from the document can be added to separate lists for separate processing or rejected altogether. Unrecognised tags will be rendered in place with a generic mechanism. All tags with a leading Available tagsA series of different tags are recognized. They capture words or other constructs, and will process the captures specially. The captures will be formatted and linked as necessary. The remaining text is treated as ordinary wikitext. If a tag taking captures fails to detect a capture, then possible captures will be successively pushed out, ultimately pushing all possible captures into the following text. This can be used in some cases to avoid using a specific capture, but is an indication that the documentation is broken. It is the intention to support the listed tags, but others can be added later. The block tags from JSdoc could be a source for additional entries.[1]
Inferred tagsSome tags will be extracted from the following block of code if missing (it is the intention to support these)
Additional commentsThere are available block comments in Lua, and they can also be used in code documented with LuaDoc. The commented blocks will be removed before further processing, making the resulting documentation stripped down to the bare running code. In Lua a block comment starts like --[[ print(10) -- no action (comment) --]] Now, if we add a single hyphen to the first line, the code is in again: ---[[ print(10) --> 10 --]] To formalize this a little bit we will say that LuaDoc only act upon comments that are on a line by themselves. Other block comments are simply left as they are. Block comments can be specified a bit more, leading to nested comments. The regex we are using for block comments is like External links
}} |
| 随便看 |
|
开放百科全书收录14589846条英语、德语、日语等多语种百科知识，基本涵盖了大多数领域的百科知识，是一部内容自由、开放的电子版国际百科全书。