This is automatically generated documentation. Edit after the "COMMENTS" heading; changes to the main body will be lost.
how to write Click element documentation
Documentation for a Click element is automatically generated from formatted comments in its header files. This manual page describes how to write one of these formatted comments.
Click element documentation syntax is based on Perl-style PODs; see perlpod(1) for more information. However, not all POD constructs are usable in element documentation at the moment; and Click element documentation is line-oriented, not paragraph-oriented.
These are the sectioning commands and the sections they correspond to, listed in the conventional order.
Each piece of documentation is stored in a single block comment
/*...*/'. Two kinds of block comment are recognized:
/* =c ElementName(...) ... and so on ... */ /* * =c * ElementName(...) * ... and so on ... */
In the first form, commands and normal text MUST begin in the first column
of each line. In the second form, commands and normal text MUST begin in
the fourth column of each line, immediately following the initial star and
* '. Indented lines are treated as verbatim text, as in
Commands are lines that begin with '
=' and a lower-case letter.
There are two kinds of commands, those that start new sections and those
that occur within sections. There is also a set of formatting
commands -- for turning text bold, for example -- that occurs inside normal
text; they are described in the next section.
=csection gives the element's name and any of its configuration arguments. For example: =c IPEncap(PROTOCOL, SADDR, DADDR) Configuration arguments should be specified as all-upper-case words. The description section will use those upper-case words to talk about the arguments. Use brackets to show that an argument is optional: =c UDPIPEncap(SADDR, SPORT, DADDR, DPORT [, CHECKSUM?]) Do not use anything more complicated than brackets. If an element has complex syntax, either use upper-case words and talk about the syntax more in the description section, or give multiple lines: =c ControlSocket(tcp, PORTNUMBER [, READONLY?]) ControlSocket(unix, PORTNUMBER [, READONLY?]) ('tcp' and 'unix' are lowercase because they should be typed verbatim.)
=processingsection from the element's processing() method, if possible.
write-only', or '
read/write'). The following text should describe that handler. For example: =h capacity read/write Returns or sets the queue's capacity.
tcpdump(1)', or text references, like 'RFC 959: File Transfer Protocol'. However, the first paragraph in the section is special; there, you can just give element names without '
(n)' suffixes. If one of these references occurs in some other section, it will be formatted like a link. For example, in =d This element is like Queue. =a Queue the mention of '
Queue' in the description section will be formatted like a link.
=over. It is illegal to use
=itemoutside of any
=overlist. The text of the item is text. If you are creating a bulleted list, use '
*' as the text; if you are creating a numbered list, use '
2.', and so forth.
=for, but can encompass multiple paragraphs. It outputs text in between the
=begincommand and the
=endcommand only when generating documentation in format.
Each line that doesn't begin with '
=' and a lower-case letter is
treated as text. (Unless it starts with a space or tab; see verbatim text,
below.) This text is formatted nicely, and perhaps even justified. You can
use several formatting commands inside normal text; they consist of an
uppercase letter, followed by '
<', some text, and '
B<...>and so forth, or to prevent words from being highlighted.
E<star>is '*', and
E<eq>is '='. This is useful for typing one of these characters in a context that would seem like a command or formatting command.
Lines that start with a space or tab character are printed out verbatim -- that is, without any changes, and with the line breaks and indentation you specified. You can't use formatting commands in verbatim text. Verbatim text is useful for showing example code; for example:
This code q :: Queue; ... -> RED(5, 50, 0.02) -> q -> ... adds RED dropping to q.
/* =c * Align(MODULUS, OFFSET) * =s modification * aligns packet data * =d * Aligns packet data. Each input packet is aligned so that * its first byte is OFFSET bytes off from a MODULUS-byte * boundary. This may involve a packet copy. * * MODULUS I<must> be 2, 4, or 8. * =n * The click-align(1) tool will insert this element * automatically wherever it is required. * =e * ... -> Align(4, 0) -> ... * =a AlignmentInfo, click-align(1) */
/* =c * Counter([TYPE]) * =s measurement * measures packet count and rate * =d * Passes packets unchanged from its input to its output, * maintaining statistics information about packet count and * rate if TYPE is "packets", or byte count and byte rate if * TYPE is "bytes". The default TYPE is "packets". * =h count read-only * Returns the number of packets/bytes that have passed through. * =h rate read-only * Returns the recent arrival rate (measured by exponential * weighted moving average) in packets/bytes per second. * =h reset write-only * Resets the count and rate to zero. */
perlpod(1), click(1), click(5)
Eddie Kohler, firstname.lastname@example.org
Robert Morris, email@example.com