File: tags.txt

package info (click to toggle)
pike7.8 7.8.866-7
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 69,304 kB
  • ctags: 28,082
  • sloc: ansic: 252,877; xml: 36,537; makefile: 4,214; sh: 2,879; lisp: 655; asm: 591; objc: 212; pascal: 157; sed: 34
file content (147 lines) | stat: -rw-r--r-- 4,899 bytes parent folder | download | duplicates (11)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
                        +-------------------+
                        | Pike autodoc tags |
                        +-------------------+

We have defined some different categories of markup, each with its own
semantics. Seen from the parser, there are two main construct levels:

* The "what-are-we-documenting level" constructs; @decl for Pike files
  and @module, @endmodule, @class and @endclass on top of that for C
  files. These are the meta level tags covered in section a).

* Inside-of-comment level constructs for documentation markup,
  covered in sections b), c) and d).


All markup can also be divided into categories based on their look
and semantics; there are three categories here (with examples):

* Grouping constructs that mark the opening/closing of a section of
  some sort (@mapping/@endmapping, @dl/@enddl, @module/@endmodule).
  Most of these not already covered by secion a) appear in b).

* subdividers that break up an outer grouping construct into
  subsections (@member, @item, @param)

* short text markup constructs that basically map to XML containers
  (@i{...@}, @ref{...@})


======================================================================
a) Meta level tags - used for targeting the documentation string
----------------------------------------------------------------------

These tags all serve the purpose of denoting what pike entities your
comments should be tied to. This is particularly needed in (and in
part only applies to) C files, where the autodoc extractor does not
try to interpret and parse class and method definitions.

Keyword:   @module
Legal for: C files only (neither needed nor legal for Pike files)
Arguments: (the last segment of) the module name (ie no "." allowed)

Example: To document the module Parser.XML module, you need two
consecutive module tags:

  /*! @module Parser */
  /*! @module XML */

A @module keyword sets the scope of documentation comments following
it. @module tags nest, as shown in the example above, and must be
ended with a matching number of @endmodule tags, as in:

  /*! @endmodule XML */
  /*! @endmodule Parser */

A @module keyword may also have a text child documenting the module
itself:

  /*! @module Parser
   *!
   *! The common roof under which parsers of various kinds, such as
   *! @[Parser.XML], @[Parser.Pike] and @[Parser.C] are housed.
   */

There are two special @module targets available; the "predef::" module
and the "lfun::" module. The predef:: module, although more of a scope
than a module, contains the definitions for all methods in Pike's
predef:: scope, as in:

/*! @module predef::
 *!   @decl int equal(mixed a, mixed b)
 *!   	This function checks if the values @[a] and @[b] are equal.
 *! @endmodule
 */

The "lfun::" module scope does not legally exist in Pike, but it
houses the docs for all lfuns (the virtual methods for fulfilling the
Pike object API). An example:

/*! @module lfun::
 *!   @decl int(0..1) `!=(mixed arg1, mixed arg2, mixed ... extras)
 *!     The inequality operator.
 *! @endmodule
 */

This also means that referencing (via @ref{...@} or @[...]) the lfun
documentation strings can be done using @[lfun::`!=] and the like, as
can predefs via @[predef::sort()] et cetera.


Keyword:   @endmodule
Legal for: C files only (neither needed nor legal for Pike files)
Arguments: (the last segment of) the module name (optional)

When the optional argument to @endmodule is given (for code clarity),
the extractor will verify that the module scope you close was indeed
the one you opened, as in the @module example above. The following
would trigger an error:

  /*! @module Parser
   *! @module XML */

  /*! ... some autodoc comments ... */

  /*! @endmodule Parser
   *! @endmodule XML */

while the same example, ending in

  /*! @endmodule
   *! @endmodule */

would be considered legal.


Keyword:   @class
Legal for: C files only (neither needed nor legal for Pike files)
Arguments: (the last segment of) the class name (ie no "." allowed)

Example: to document the Process.create_process class, you would use:

  /*! @module Process
   *! @class create_process */

And end the scope similar to @module:

  /*! @endclass create_process
   *! @endmodule Process */

Like @module tags, @class tags may be nested any number of levels
(when documenting subclasses to subclasses to subclasses to ...).


Keyword:   @endclass
Legal for: C files only (neither needed nor legal for Pike files)
Arguments: (the last segment of) the class name (optional)

When the optional argument to @endclass is given (for code clarity),
the extractor will verify that the class scope you close was indeed
the one you opened, just as with @endmodule above.


Keyword:   @decl
Legal for: All source code (C and Pike files)
Arguments: (the last segment of) the identifier name (ie "." illegal)

The @decl keyword is used to target a specific (...more to come! :-)