It is of course recommended that everyone follows all of these guidelines, but to some are more important than others. These are marked (required). "; TekstEnd(); /* * */ Odin32DBNaslov("File Header (required)","fileheader"); TekstBeg(); echo " Each and every source file should start with a header like this: "; TekstEnd(); CodeBeg(); echo " /* \$Id: Odin32GuidelineDocumentation.phtml,v 1.5 2001-09-05 21:40:46 bird Exp $ * * <insert file description here> * * Copyright (c) <YYYY>[-YYYY] <author 1> [* Copyright (c) <YYYY>[-YYYY] <author 2>] * * Project Odin Software License can be found in LICENSE.TXT */"; CodeEnd(); TekstBeg(); echo " The file header starts with CVS keyword, \$Id\$. When commiting the file CVS expandes this keyword. Following is a blank line and a description of the file contents. Then a blank line and copyright info for all authors. As the final statement is the license information.
Note: If someone like to include CVS keywords (\$Log\$, \$Header\$, \$...) other that \$Id\$, we will have to discuss this in the WAI and MAD teams. As long as a keyword is not decided used (by the MAD or/and the WAI teams), it should not be used! "; TekstEnd(); /* * */ Odin32DBNaslov("Function Header (required)", "functonheader"); TekstBeg(); echo " A function header is required for all API functions and recommended for all other functions. Using and maintaining the described function header will allow us to monitor the progress of the project and generate documentation.
Note: The function header which is described here is not the only one found in the sources. You are discouraged from using other function header(s) than the one described here. "; TekstEnd(); /* * */ Odin32DBPodNaslov("SDS Function Header", "sdsfunctionheader"); TekstBeg(); echo " (SDS is a Javadoc styled documentation system for many languages. We will use some of the standard SDS tags, and add three Odin specific ones; @status, @group and @author.)
First have a look at an example function header: "; TekstEnd(); CodeBeg(); echo " /** * The OpenFileMappingA function opens a named file-mapping object. * @returns HANDLE to map object. * @param dwDesiredAccess access mode * @param bInheritHandle inherit flag * @param lpName address of name of file-mapping object * @status STUB * @group Filemapping * @author Patrick Haller [Mon, 1998/06/15 08:00] */ HANDLE WIN32API OS2OpenFileMappingA(DWORD dwDesiredAccess,"; CodeEnd(); TekstBeg(); echo " As you see, the the different parts of the header is identified by a tag (also called keyword). A tag starts with the '@' character. Note that the @param tag is kind of special as it has a parameter (parametername) and may occur more than once (with different parameternames).
Function headers (methods) have the following tags (keywords):
| Tag | Description |
| @desc | General description. (default) |
| @return | What the function returns (Alias: @returns) |
| @param |
Parameters to the function. |
| @status | Function status. See "; AnchNaslov("Function State.", "functionstate", ""); echo " |
| @group |
Name of the API Group the function belongs into.
This have to be a valid API Group name. See "; LocLink("Odin32DB.phtml?apigroups=1", "here"); echo " for current API groups. |
| @time | Time complexity or estimated time use. |
| @sketch | A sketch of the method, usually for design. |
| @author | This is a list of authors. Authors are separated by ',' or by new-line. Make sure to use exactly the same name/signature each time. |
| @remark | Any remarks. |
"; TekstBeg(); echo "Since @desc is default, this form:"; TekstEnd(); CodeBeg(); echo " /** this is a method-description */ int foo();"; CodeEnd(); TekstBeg(); echo "is equivalent with:"; TekstEnd(); CodeBeg(); echo " /** @desc this is a method-description */ int foo();"; CodeEnd(); TekstBeg(); echo " Note: that you should only include those tags that you use or intend to use. If you don't use the @time tag don't waste a line on it. "; TekstEnd(); /* * Function State */ Odin32DBPodNaslov("Function State","functionstate"); TekstBeg(); echo " For API functions we will try monitor the implementation progress. To aid us we will assign a state to the API function which tells us how far the implementation has come. The @status tag is intended to hold this information. The @status tag is used when automagically updating the Odin32 API Database. So while working on an API function, you'll have to update this field so it reflects the current implementation state of the function. (If you don't update it, the whole point is gone...)
The status is a set of keywords which describes the function state. (Additional words in the status field is ignored.)
"; TekstEnd(); echo "
| % | Keyword | Description |
| ".$aState["weight"]."% | ".$aState["name"]." | ".$aState["description"]." |
\n"; TekstBeg(); echo " Note: The Open32 keyword should be used when the implementation of the API calls an Open32 function. Even if you''ve written 1000 lines of code fixing Open32 bugs, as long as it depends on Open32 directly in the implementation.
Note2: The % column in the table is the compleatage percent of a function in the given state. "; TekstEnd(); /* * Design notes. */ Odin32DBNaslov("Design Notes","design"); TekstBeg(); echo " Experimental - expect addition/changes
From time to other someone will feel the urge to write a few (or many) lines about the design of a module, subsystem, tool or whatever, which isn't related to a specific function. For that purpose there is a tag, @design, which you can place whereever you whan't in the sourcecode, and write about how things work. The design notes are intented to be at a level higher than function or maybe even file level of documentation.
The @design-tag have a couple of options, which are used to order them and to give a title to the design note.
Syntax: @design <module sequence nbr> <design note title>
The module sequence nbr is a sequence number used to order the notes this for the module (ie. dll) when the designnotes are put together for an entire module.
The design note title is the title of the design note. This also used when the notes are collected for an entire module.
"; TekstEnd(); /* * Class Documentation */ Odin32DBNaslov("Classes and Methods (SDS)","classesandmethods"); TekstBeg(); echo " We need a way of describing and document classes and methods (class functions) in the Odin32 API. Though classes and methods are not exported directly in the API, they are used to implemented very much of it. For example the DDRAW and DSOUND DLL exports classes through function tables.
The following sub-sections is an excerpt from the SDS documentation adapted for use in Project Odin. "; TekstEnd(); /* * */ Odin32DBPodNaslov("Briefly About SDS", "aboutsds"); TekstBeg(); echo " SDS (Software Development Foundation) is designed (by Stig E. Sandøe) to be similar to JavaDoc but operate on C++, C, Java, Lisp, and other languages. It consists of a documentation style and a set of utilities which parses the source- and header-files and generates a set of HTML pages and class diagrams. We don't use the SDS tools yet, rather or homegrown stuff, the documentation style is very useful to attach some describing words to classes and their methods in a structured and uniform way.
The SDS documentation style is used by the win32k sources. For more on SDS look "; UrlLink("sds.sourceforge.net/", "here"); echo ".\n"; TekstEnd(); /* * The Class-description Tags */ Odin32DBPodNaslov("The Class-Description Tags", "sdsclasstags"); TekstBeg(); echo " An Example: "; TekstBeg(); CodeBeg(); echo " /** * @prop Here is the short description of class Foo * @desc Here is the description of class Foo * @purpose I describe the purpose of class Foo here. * @author Stig E. Sandoe. */ class Foo { ... };"; CodeEnd(); /* A More Thorough Description */ PodPodNaslov("A More Thorough Description"); TekstBeg(); echo " Classes has the following keywords: "; TekstEnd(); echo "
| Tag | Description |
| @desc | Starts the general description-field for a class. (default) |
| @shortdesc | Short description (Alias: @memo) |
| @dstruct | Starts the field describing the data-structure of the class, and where it fits into the pig picture. |
| @version | Specifies the versionname/number of the class. (Alias: @vername) |
| @verdesc | Description of diffs in \"this\" version. |
| @author | Specifies the author of the class. |
| @approval | Specifies who have given final approval of the documentation/implementation of a class. |
"; TekstEnd(); CodeBeg(); echo " class Foo { /** Documentation before the method */ doFrob(); int length() { /** Doc. inside the method */ ... } }; /** More doc. before the mothod */ Foo::doFrob() { /** Doc. inside the implementation */ }"; CodeEnd(); /* A More Thorough Description */ PodPodNaslov("A More Thorough Description"); TekstBeg(); echo " Methods have the following keywords:
"; TekstEnd(); echo "
| Tag | Description |
| @desc | General description. (default) |
| @return | What the function returns (Alias: @returns) |
| @param |
Parameters to the function. |
| @status | Function status. See "; AnchNaslov("Function State.", "functionstate", ""); echo " |
| @time | Time complexity or estimated time use. |
| @sketch | A sketch of the method, usually for design. |
| @author | This is a list of authors. Authors are separated by ',' or by new-line. Make sure to use exactly the same name/signature each time. |
| @remark | Any remarks. |