1 2 3 4 5 6 7 8 9 10 11
12 package xdc.tools.cdoc;
13
14 /*!
15 * XDCspec doc markup language examples
16 *
17 * This module demonstrates the features of XDCspec doc and gives usage
18 * examples for the XDCspec doc markup language. View the source text of this
19 * .xdc file for details on how to use these examples.
20 *
21 * @a(HEADINGS)
22 * Major headings can be inserted into the document using the following
23 * syntax:
24 * @p(code)
25 * @@tag(headingText)
26 * @p
27 *
28 * The available tags are:
29 * @p(dlist)
30 * - `@@a(headingText)`
31 * Add a heading to the end ("a" for "after") of the details section.
32 * - `@@b(headingText)`
33 * Add a heading to the start ("b" for "before") of the details section.
34 * @p
35 *
36 * Since XDCtools 3.05, @@a and @@b tags can accept space characters in headings.
37 * Prior to this, heading text could contain no spaces.
38 *
39 * @a(PARAGRAPH FORMATTING)
40 * Paragraphs can be marked in several different styles using the
41 * following syntax:
42 * @p(code)
43 * @@p(style)
44 * paragraph text here...
45 *
46 * another paragraph...
47 * @@p
48 * @p
49 *
50 * The available paragraph styles are:
51 * @p(dlist)
52 * - `@@p(text) or @@p`
53 * Plain text -- this is the default.
54 * - `@@p(code)`
55 * Fragments of source code or pseudo-code. Paragraphs of this
56 * type are rendered in a fixed-width font.
57 * - `@@p(html)`
58 * HTML markup. Paragraphs of this type are copied directly into the
59 * XDCspec doc output, with no interpretation.
60 * @p
61 *
62 * @a(CHARACTER FORMATTING)
63 *
64 * @a(LIST TYPES)
65 * Lists in several styles can be created using the syntax:
66 * @p(code)
67 * @@p(style)
68 * - first list item
69 * continued...
70 * - second list item
71 * @@p
72 * @p
73 * The available list styles are bulleted list, numbered list, and
74 * definition list, and they look like this:
75 * @p(blist)
76 * - The `blist` bulleted list style is an unnumbered, unordered list
77 * - Rendered using the HTML `<UL>` element.
78 * @p
79 * @p(nlist)
80 * - The `nlist` numbered list style is an ordered, numbered list
81 * - Rendered using the HTML `<OL>` element.
82 * @p
83 * @p(dlist)
84 * - `Definition List`
85 * The `dlist` definition list style has a minor heading for
86 * each item in the list
87 * - `Rendering`
88 * Rendered using the HTML `<DL>` element.
89 * @p
90 *
91 * @a(CDOC HYPERLINKS)
92 * HTML hyperlinks between XDCspec doc pages can be inserted using the
93 * `{@link}` inline keyword. `link` takes as a parameter the name of an XDCspec
94 * element, and optionally some additional formatting text. The
95 * XDCspec element can name a package, a module or interface, or a
96 * declaration within a module or interface. The general syntax is:
97 * @p(code)
98 * {@@link [pkgName.][modName][#decl][suffText] [altText]}
99 * @p
100 * where:
101 * @p(dlist)
102 * - `pkgName`
103 * is the name of a package.
104 * - `modName`
105 * is the name of a module or interface within the package.
106 * - `decl`
107 * is the name of a declaration within the module or interface,
108 * for example a function or config parameter.
109 * Note that `decl` is delimited by a '`#`' character to distinguish
110 * it from the name of a package, module or interface.
111 * - `suffText`
112 * is text to be appended to the text of the link. For example, '`()`'
113 * might be appended to denote a void function. The suffix text must
114 * contain no spaces.
115 * - `altText`
116 * is alternate text to be used instead of the XDCspec name of the
117 * link target.
118 * @p
119 *
120 * @p(html)
121 * <table cellSpacing="2" cellPadding="2" width="100%" border="1">
122 * <tbody>
123 * <tr>
124 * <th><B>Write this:</B></th>
125 * <th><B>To reference this:</B></th></tr>
126 * <tr>
127 * <td>{@@link <i>pkgName</i>}</td>
128 * <td>a package</td></tr>
129 * <tr>
130 * <td>{@@link <i>pkgName</i>.<i>moduleName</i>}</td>
131 * <td>a module</td></tr>
132 * <tr>
133 * <td>{@@link <i>moduleName</i>}</td>
134 * <td>a module in the same package</td></tr>
135 * <tr>
136 * <td>{@@link <i>pkgName</i>.<i>moduleName</i>#<i>declName</i>}</td>
137 * <td>a decl in a module</td></tr>
138 * <tr>
139 * <td>{@@link <i>moduleName</i>#<i>declName</i>}</td>
140 * <td>a decl in the same package</td></tr>
141 * <tr>
142 * <td>{@@link #<i>declName</i>}</td>
143 * <td>a decl in the same module</td></tr>
144 * <tr>
145 * <td>{@@link #<i>declName</i>(<i>arg1</i>,<i>arg2</i>)}</td>
146 * <td>a function with explicit args given in <i>suffText</i></td></tr>
147 * <tr>
148 * <td>{@@link #<i>declName</i> defined here}</td>
149 * <td>a decl with the explicit link text "defined here"</td></tr>
150 * </tbody>
151 * </table>
152 * @p
153 *
154 * Examples are:
155 * @p(dlist)
156 * - {@link Example#AStruct}
157 * - {@link xdc.tools.cdoc.Example}
158 * - {@link Example#AStruct a struct with alternate text}
159 * @p
160 *
161 * @see Example#AStruct
162 *
163 * @a(EXTERNAL HTML LINKS)
164 * Documentation can also include HTML hyperlinks to web sites, using
165 * the syntax:
166 * @p(code)
167 * {@@link http://serverName/pathName[#anchor] [altText]}
168 * @p
169 * The URL must include a resource type, typically "http:" or "ftp:".
170 *
171 * Examples are:
172 * @p(dlist)
173 * - {@link http://ti.com}
174 * - {@link http://ti.com Texas Instruments}
175 * @p
176 *
177 * @a(LINKING TO OTHER DOCUMENTATION FILES)
178 * It is possible to deliver other documentation files along with a
179 * package, and link to it from XDCspec doc. The documentation files must
180 * be placed in a subdirectory of the package with the name `'doc-files'`.
181 * Hyperlinks to files in this directory are created using the syntax:
182 * @p(code)
183 * {@@link ./doc-files/filename[#anchor] [altText]}
184 * {@@link pkgDir/doc-files/fileName[#anchor] [altText]}
185 * @p
186 *
187 * The file name is specified using the same syntax as the `xdc.findFile()`
188 * function. That is, filenames within the current package must begin with "./".
189 * Links to files in other packages must use the fully qualified package name,
190 * with slashes ('/') instead of dots ('.') in the name.
191 *
192 * @p(html)
193 * <table cellSpacing="2" cellPadding="2" border="1">
194 * <tbody>
195 * <tr>
196 * <th><B>Write this:</B></th>
197 * <th><B>To reference this:</B></th></tr>
198 * <tr>
199 * <td>{@@link ./doc-files/<i>filename</i> }</td>
200 * <td>a file in the current package</td></tr>
201 * <tr>
202 * <td>{@@link <i>pkgDir</i>/doc-files/<i>filename</i> }</td>
203 * <td>a file in another package</td></tr>
204 * </tbody>
205 * </table>
206 * @p
207 *
208 * Examples are:
209 * @p(dlist)
210 * - {@link ./doc-files/example.html}
211 * - {@link xdc/tools/cdoc/doc-files/example.html}
212 * @p
213 *
214 * @a(LINKING TO DOXYGEN DOCUMENTATION)
215 * It is possible to link to Doxygen documentation.
216 * Hyperlinks to are created using the syntax:
217 * @p(code)
218 * {@@link doxy(name)}
219 * @p
220 * In a SEE section use:
221 * @p(code)
222 * doxy(name)
223 * @p
224 *
225 * @p(html)
226 * <table cellSpacing="2" cellPadding="2" border="1">
227 * <tbody>
228 * <tr>
229 * <th><B>To link to:</B></th>
230 * <th><B>Use:</B></th>
231 * <th><B>Example:</B></th></tr>
232 * <tr>
233 * <td>File</td>
234 * <td><i>filePrefix</i><B>.</B><i>fileSuffix</i></td>
235 * <td>doxy(Engine.h)</td></tr>
236 * <td>Function</td>
237 * <td><i>functionName</i><B>()</B></td>
238 * <td>doxy(Engine_open())</td></tr>
239 * <td>#define</td>
240 * <td><B>#</B><i>defineName</i></td>
241 * <td>doxy(#Engine_GTNAME)</td></tr>
242 * <td>Struct</td>
243 * <td><i>structName</i></td>
244 * <td>doxy(IALG_Fxns)</td></tr>
245 * <td>Struct field</td>
246 * <td><i>structName</i><B>::</B><i>structField</i></td>
247 * <td>doxy(IALG_Fxns::algAlloc)</td></tr>
248 * <td>Enum</td>
249 * <td><i>enumName</i></td>
250 * <td>doxy(IALG_MemAttrs)</td></tr>
251 * <td>Enumerator</td>
252 * <td><i>enumName</i><B>::</B><i>enumerator</i></td>
253 * <td>doxy(IALG_MemAttrs::IALG_PERSIST)</td></tr>
254 * <td>Typedef</td>
255 * <td><B>::</B><i>typedefName</i></td>
256 * <td>doxy(::Engine_Handle)</td></tr>
257 * <td>Variable</td>
258 * <td><B>#</B><i>variableName</i></td>
259 * <td>doxy(#Engine_ATTRS)</td></tr>
260 * </tbody>
261 * </table>
262 * @p
263 *
264 * See xdc.tools.cdoc usage for how to specify the location of the Doxygen files.
265 *
266 */
267 metaonly module Markup {
268 }
269 270 271
272