Elementdoc

elementdoc

how to write Click element documentation

Description

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.

Command Quick Reference

These are the sectioning commands and the sections they correspond to, listed in the conventional order.

• =c

  SYNOPSIS

• =s category

  NAME (one-line summary)

• =io

  INPUTS AND OUTPUTS

• =processing

  PROCESSING TYPE

• =d

  DESCRIPTION

• =n

  NOTES

• =e

  EXAMPLES

• =h name type

  ELEMENT HANDLERS

• =a

  SEE ALSO

• =head1 text

  other heading

These are the other commands used in element documentation.

• =head2 text

  subheading

• =over amount

  begin item list

• =item text

  add item

• =back

  end item list

• =for format

  selective formatting

• =begin format

  selective formatting

• =end format

  selective formatting

• =deprecated new-element

  element is deprecated

These are the formatting commands, used inside ordinary text.

• B<text>

  boldface

• I<text>

  italics

• U<text>

  underlined (if possible)

• P<text>

  plain text (i.e., no automatic links)

• C<text>

  code (fixed-width)

• F<text>

  filename (italics)

• L<text|link>

  hyperlink

• N<>

  line break

• E<name>

  entity

• V<text>

  hide text

And these are the category keywords, used in the summary section to categorize elements.

• basicsources

  Basic Sources and Sinks

• classification

  Basic Classification and Selection

• basictransfer

  Basic Packet Transfer

• counters

  Counters

• timestamps

  Timestamps

• basicmod

  Basic Packet Modification

• storage

  Packet Storage

• aqm

  Active Queue Management

• scheduling

  Packet Scheduling

• shaping

  Traffic Shaping

• information

  Information Elements

• netdevices

  Network Devices

• comm

  Host and Socket Communication

• ethernet

  Ethernet

• arp

  ARP

• ip

  IPv4

• iproute

  IPv4 Routing

• icmp

  ICMP

• nat

  Network Address Translation

• tcp

  TCP

• udp

  UDP

• app

  Applications

• traces

  Trace Manipulation

• ipmeasure

  TCP/IP Measurement

• aggregates

  Aggregates

• ip6

  IPv6

• ipsec

  IPsec

• crc

  CRCs

• paint

  Paint Annotations

• annotations

  Annotations

• debugging

  Debugging

• control

  Control

• smpclick

  Multithreaded Click

• test

  Regression Tests

Comment Syntax

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 spaces ‘ * ’. Indented lines are treated as verbatim text, as in POD.

Commands

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.

Section Commands

• =s [category]

  Begin the summary section. This should contain a very short, one-line summary of the element’s function. For example, for a Queue element:

     =s storage
       stores packets in a FIFO queue
    

  The summary text should generally be a verb phrase.

  The optional category specifies one or more element categories into which this element fits, separated by commas. Specifying meaningful categories helps a lot; documentation tools use categories to divide elements into manageable groups. Use existing categories, defined by the list of category keywords above in the Command Quick Reference, or create your own.

• =c

  Begin the synopsis section. This section is mandatory.

  The =c section 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:

<pre>   =c
   UDPIPEncap(SADDR, SPORT, DADDR, DPORT &#91;, CHECKSUM?&#93;)
</pre>

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:

<pre>   =c
   ControlSocket(tcp, PORTNUMBER &#91;, READONLY?&#93;)
   ControlSocket(unix, PORTNUMBER &#91;, READONLY?&#93;)
</pre>(‘tcp’ and ‘unix’ are lowercase because they should be typed verbatim.)

• =io

  Begin the inputs and outputs section. This section mentions how many inputs and outputs the element has. It is usually quite short; for example:

     =io
       None
    

  This section is optional, and most elements don’t bother to have one; they

  mention inputs and outputs in the description section.

• =processing

  Begin the processing type section. This section mentions the processing types of the element’s input and output ports. It is usually quite short; for example:

     =processing
       Push inputs, pull outputs
    

  This section is optional. Documentation processing tools will generate a

  =processing section from the element’s processing() method, if possible.

• =d

  Begin the description section. This section tells how the element should be used. It is usually the longest section. When mentioning configuration arguments, use the upper-case words given in the =c section.

• =n

  Begin the notes section.

• =e

  Begin the examples section.

• =h handlername type

  Begin a handler description. Use this section to describe any special handlers that the element installs. Handlername should be the name of the handler, and type its type (either ‘read-only’, ‘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.
    

• =a [text]

  Begin the "see also" section. Use this section to mention other relevant elements and programs, when appropriate. The more references, the better. For example:

     =a RED, FrontDropQueue
    

  The optional _text_ is just part of the body of the section.

  The references in this section should be either manual page references, like ‘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

<pre>   =d
   This element is like Queue.
   =a Queue
</pre>the mention of ‘<tt>Queue</tt>’ in the description section will be formatted
like a link.

• =head1 sectionname

  Begin a section other than those listed. Sectionname is the name of the section.

Other Commands

• =head2 text

  Produce a subheading with text as the text.

• =over amount

  Begin a list of items that is indented by amount characters. (Some translators may ignore amount.)

• =item text

  Add an item to the latest list opened by =over. It is illegal to use =item outside of any =over list. 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 ‘1.’, ‘2.’, and so forth.

• =back

  Close the latest list opened by =over.

• =for format

  Output the next paragraph only when generating documentation in format. Valid formats include ‘html’, ‘man’, and ‘roff’. The paragraph ends at the next command or blank line, and it consists of text in the given format, not element documentation. For example, this code includes a picture in HTML mode:

     =for html
       <p>Here is a pretty picture:
       <img src="pretty.gif"></p>
    
       Back to B<normal text> here.
    

• =begin format ... =end format

  This is like =for, but can encompass multiple paragraphs. It outputs text in between the =begin command and the =end command only when generating documentation in format.

• =deprecated new-element

  This command notes that the element has been deprecated in favor of new-element. It does not result in any output.

Text

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 ‘>’. The commands are:

• B<text>

  Print text in boldface.

• I<text>

  Print text in italic.

• R<text>

  Print text in roman. Useful inside B<...> and so forth, or to prevent words from being highlighted.

• C<text>

  Print text like source code, in a constant-width font.

• F<text>

  Print text like a filename. By default, filenames appear in italics.

• L<text|link>

  Print text as a hyperlink with destination link. This usually just comes out as text.

• N<>

  Put a line break here.

• E<name>

  Print the HTML-style entity named name. There are six entities: E<lt> is ‘<’, E<gt> is ‘>’, E<amp> is ‘&’, E<solid> is ‘/’, E<verbar> is ‘|’, 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.

• V<text>

  Do not print text.

Verbatim Text

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.

Examples

/* =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.
 */

See Also

perlpod(1), click, click

Author

Eddie Kohler, kohler@seas.harvard.edu
Robert Morris, rtm@lcs.mit.edu
http://www.pdos.lcs.mit.edu/click/