Download Reference Manual
The Developer's Library for D
About Wiki Forums Source Search Contact

Documenting the Code

Each module should include a header indicating a few key fields. Note that the license is not copied verbatim into the header, but is instead referred to via a DDoc link. An example header is shown below, for purposes of illustration:

/*******************************************************************************

        copyright:      Copyright (c) 2004 Kris Bell. All rights reserved

        license:        BSD style: $(LICENSE)

        author:         Kris

*******************************************************************************/

module tango.io.Exception;

Method commentary should include appropriate tags from the following set: Params, Returns, and Remarks. The description should always include a short synopsis at the start, a populated Remarks tag at the end, and appropriate use of Params, Returns, and Examples. We should strive to retain a consistent order, layout, and capitalization of these tags as follows:

/*******************************************************************************
        
        Access buffer content

        Params: 
        size =  number of bytes to access
        eat =   whether to consume the content or not

        Returns:
        the corresponding buffer slice when successful, or null if there 
        is not enough data available (Eof; Eob).

        Remarks:
        read a slice of data from the buffer, loading from the conduit as 
        necessary. The specified number of bytes is sliced from the buffer, 
        and marked as having been read when the 'eat' parameter is set true. 
        When 'eat' is set false, the read position is not adjusted.

        Note that the slice cannot be larger than the size of the buffer; 
        use method get(void[]) instead where you simply want the content 
        copied, or use conduit.read() to extract directly from an attached 
        conduit. Also note that if you need to retain the slice, then it
        should be .dup'd before the buffer is compressed or repopulated.

        Examples:
        ---
        // create a buffer with some content 
        auto buffer = new Buffer ("hello world");

        //consume everything unread
        auto slice = buffer.get (buffer.readable);
        ---

*******************************************************************************/

Add usage examples where appropriate, using the DDoc "---" convention to highlight the code-segment itself. Use of the Standards tag is also encouraged where appropriate.

Links to other modules from within the documentation can take advantage of the $(CODEURL) macro. For example, to link the source code for the File module, you could use $(LINK $(CODEURL tango.io.File)). Linking to the API doc would use $(LINK $(APIURL tango.io.File)) instead.

A Note about Comment Styles

Everyone has their own favourite style for coding and for comments. We expect the module-header to look as it does above, but code-comments can be in your preferred style (as above, or /// or /**). The information within the comment is the important part.