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.