16 | Architecture
67 | 68 |
69 | LuaDoc's processing can be divided in two distinct steps: parsing and
70 | generation. The parsing step take as input a set of .lua files
71 | and must produce a Documentation object. A generator takes a
72 | Documentation object as input and produces a set of output files.
73 | It's up to the generator to decide which output format it will generate.
74 |
76 | The parsing step is executed by a component called
77 | taglet, while the generation is handled by a
78 | component called doclet. This architecture is
79 | shown below.
80 |
82 | 
83 |
Taglet
86 |
87 | LuaDoc does not impose a documentation format. Instead, it relies on an internal
88 | representation of the documentation. This representation is described in the
89 | Documentation section. If the developer wants to
90 | use a custom documentation format the taglet component can be
91 | replaced.
92 |
94 | Writing a new taglet is a matter a implementing a single method: 95 |
96 |97 | function start (files, doc) 98 |99 |
-
100 |
- files 101 |
- a list of file (or directory) names. 102 | 103 |
- doc 104 |
- a preprocessed documentation object. 105 |
108 | LuaDoc comes bundled with a standard taglet implementation. This implementation
109 | takes all file names in the list and produce the documentation object using a set
110 | of tags described in the section How To. If an
111 | item in the list is a directory it iterates recursively through all files in the
112 | directory looking for filenames with .lua or .luadoc
113 | extensions.
114 |
Documentation
117 |118 | Instead of defining a documentation format LuaDoc defines an internal 119 | representation of a documentation object. Taglets and doclets must conform with 120 | this format. 121 |
122 |123 | The documentation object is described below. Some description elements are explained 124 | below: 125 |
126 |-
127 |
- List 128 |
- table indexed by number. Example: List<string> 129 | { 130 | [1] = "x", 131 | [2] = "y", 132 | [3] = "z", 133 | } 134 | 135 | 136 |
- HashMap 137 |
- table whose numerical indices are the key values for objects. Example: HashMap<string, string>
138 |
{ 139 | [1] = "x", 140 | [2] = "y"; 141 | [3] = "z"; 142 | ["x"] = "x coord", 143 | ["y"] = "y coord", 144 | ["z"] = "z coord", 145 | }146 |
147 |
DOCUMENTATION
150 |
151 | {
152 | files = HashMap<string, DOCUMENTATION_ELEMENT>, -- indexed by file name
153 | modules = HashMap<string, DOCUMENTATION_ELEMENT>, -- indexed by module name
154 | }
155 |
156 |
157 | DOCUMENTATION_ELEMENT
158 |
159 | {
160 | type = ["file" | "module"],
161 | name = <string>, -- full path of file or name of module
162 | doc = List<BLOCK>, -- all documentation blocks
163 | functions = HashMap<string, BLOCK>, -- only functions, indexed by function name
164 | tables = HashMap<string, BLOCK>, -- only table definitions, indexed by table name
165 | },
166 | }
167 |
168 |
169 | BLOCK
170 |
171 | {
172 | class = ["module" | "function" | "table"],
173 | name = <string>,
174 | summary = <string>,
175 | description = <string>,
176 | comment = List<string>,
177 | code = List<string>,
178 | param = HashMap<string, string>,
179 | },
180 |
181 |
182 | Doclet
183 |
184 | The primary job of an doclet is to take a
185 | Documentation object and generate some kind of output.
186 | LuaDoc is bundled with an implementation that generates HTML files.
187 |
190 | Writing a new doclet is a matter a
191 | implementing a single method:
192 |
194 | function start (doc) 195 |196 |
-
197 |
- doc 198 |
- a documentation object. 199 |