source: trunk/tools/database/www/Odin32GuidelineDocumentation.phtml@ 5655

<?php
$Naziv="Project Odin Sourcecode Documentation Guidelines";

require "stilovi.php3";
require "Odin32DBHelpers.php3";

/* Profiling */
$sPageTimer = Odin32DBTimerStart("page timer");
/* Profiling */


require "01-PreTitle.php3";
echo $Naziv;
require "02-PostTitle.php3";

require "03-MainTableBeg.php3";
require "04-ColumnOne.php3";

require "05-ColumnTwoHeader.php3";
echo $Naziv;
require "06-ColumnTwoHeader2.php3";

/* I would like to number the sections and subsections */
ODin32DBNumberSections();

/*
 *
 */
TekstBeg();
echo "
        This page describes the sourcecode documentation guildelines
        used in Project Odin.
        ";
TekstEnd();


/*
 *
 */
Odin32DBNaslov("Introduction","intro");
TekstBeg();
echo "  The documentation guidelines will keep reminding us that documentation
        is necessary; and we may benefit from it when monitoring progress.
        (Odin32 API Database) The status for each API function is essential.
        <p>
        The documentation style is based on Javadoc and
        ";
UrlLink("sds.sourceforge.net/", "SDS (Software Development Foundation)");
echo "  . We have made our own additions in form of new keywords.
        <p>
        It is of course recommended that everyone follows all of these
        guidelines, but to some are more important than others. These
        are marked <i>(required)</i>.
        ";
TekstEnd();


/*
 *
 */
Odin32DBNaslov("File Header <i>(required)</i>","fileheader");
TekstBeg();
echo "  Each and every source file should start with a header like this:
        ";
TekstEnd();
CodeBeg();
echo "
/* \$Id: Odin32GuidelineDocumentation.phtml,v 1.3 2000-08-02 02:19:10 bird Exp $
 *
 * <i>&lt;insert file description here&gt;</i>
 *
 * Copyright (c) <i>&lt;YYYY&gt;[-YYYY] &lt;author 1&gt;</i>
[* Copyright (c) <i>&lt;YYYY&gt;[-YYYY] &lt;author 2&gt;</i>]
 *
 * 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.<p>

        <b>Note:</b> 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 <i>(required)</i>", "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.<p>

        <b>Note:</b> 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 "
        <i>(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; <tt>@status</tt>, <tt>@group</tt> and <tt>@author</tt>.)</i><p>

        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 <tt>'@'</tt>
        character. Note that the <tt>@param</tt> tag is kind of special as it
        has a parameter (parametername) and may occur more than once (with
        different parameternames).<p>

        Function headers (methods) have the following tags (keywords):<p>

<table border=3>
<tr><td><b>Tag</b></td>
    <td><b>Description</b></td>
</tr>
<tr><td><tt>@desc</tt></font></td>
    <td><font size=-1>General description. (default)</td>
</tr>
<tr><td><tt>@return</tt></td>
    <td><font size=-1>What the function returns (Alias: @returns)</font></td>
</tr>
<tr><td><tt>@param <paramname></tt></td>
    <td><font size=-1>Parameters to the function.</font></td>
</tr>
<tr><td><tt>@status</tt></td>
    <td><font size=-1>
        Function status. See ";
AnchNaslov("Function State.", "functionstate", "");
echo "
    </font></td>
</tr>
<tr><td><tt>@group</tt></td>
    <td><font size=-1>
        Name of the API Group the function belongs into.
        This have to be a valid API Group name.<br>
        See ";
LocLink("Odin32DB.phtml?apigroups=1", "here");
echo " for current API groups.
    </font></td>
</tr>
<tr><td><tt>@time</tt></td>
    <td><font size=-1>Time complexity or estimated time use.</font></td>
</tr>
<tr><td><tt>@sketch</tt></td>
    <td><font size=-1>A sketch of the method, usually for design.</font></td>
</tr>
<tr><td><tt>@author</tt></td>
    <td><font size=-1>
        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.
    </font></td>
</tr>
<tr><td><tt>@remark</tt></td>
    <td><font size=-1>Any remarks.</font></td>
</tr>
</table>
<p>";

TekstBeg();
echo "Since <tt>@desc</tt> 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 "
        <b>Note:</b> that you should only include those tags that you use or
        intend to use. If you don't use the <tt>@time</tt> 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 <tt>@status</tt> tag is intended
        to hold this information. The <tt>@status</tt> 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...)<p>

        The status is a set of keywords which describes the function state.
        (Additional words in the status field is ignored.)<p>
        ";
TekstEnd();

echo "
        <table border=3>
        <tr>
            <td width=5% align=right><font size=-1><b>%</b></font></td>
            <td><font size=-1><b>Keyword</b></font></td>
            <td width=70%><font size=-1><b>Description</b></font></td>
        </tr>
        ";

require "Odin32DBConnect.php3";
$sql = "SELECT\n".
       "    name,\n".
       "    description,\n".
       "    weight,\n".
       "    color\n".
       "FROM\n".
       "    state\n".
       "ORDER BY refcode";
$result = mysql_query($sql, $db);
if ($result)
{
    while ($aState = mysql_fetch_array($result))
    {
        echo "
        <tr>
            <td align=right valign=top><font size=-1>".$aState["weight"]."%</font></td>
            <td valign=top><font size=-1 color=".$aState["color"].">".$aState["name"]."</font></td>
            <td valign=top><font size=-1>".$aState["description"]."</font></td>
        </tr>";
    }
}
else
    Odin32DBSqlError($sql);

echo "
        </table><p>\n";

TekstBeg();
echo "
        <b>Note:</b> 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.<p>

        <b>Note2:</b> The <b>%</b> column in the table is the compleatage
        percent of a function in the given state.
     ";
TekstEnd();


/*
 * Design notes.
 */
Odin32DBNaslov("Design Notes","design");
TekstBeg();
echo "
        <i>Experimental - expect addition/changes </i><p>

        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, <tt>@design</tt>, 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.<p>

        The <tt>@design</tt>-tag have a couple of options, which are used to
        order them and to give a title to the design note.<p>

        Syntax: <tt>@design &lt;module sequence nbr&gt; &lt;design note title&gt;</tt><p>

        The <tt>module sequence nbr</tt> 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.<p>

        The <tt>design note title</tt> is the title of the design note. This
        also used when the notes are collected for an entire module.<p>


        ";
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.<p>

        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&oslash;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.<p>

        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 "
<table border=3>
<tr>
    <td><b>Tag</b></td>
    <td><b>Description</b></td>
</tr>
<tr>
    <td><tt>@desc</tt></td>
    <td><font size=-1>
        Starts the general description-field for a class. (default)
    </font></td>
<tr>
    <td><tt>@shortdesc</tt></td>
    <td><font size=-1>
        Short description (Alias: <tt>@memo</tt>)
    </font></td>
<tr>
    <td><tt>@dstruct</tt></td>
    <td><font size=-1>
        Starts the field describing the data-structure of the class,
        and where it fits into the pig picture.
    </font></td>
<tr>
    <td><tt>@version</tt></td>
    <td><font size=-1>
        Specifies the versionname/number of the class.
        (Alias: <tt>@vername</tt>)
    </font></td>
<tr>
    <td><tt>@verdesc</tt></td>
    <td><font size=-1>
        Description of diffs in \"this\" version.
    </font></td>
<tr>
    <td><tt>@author</tt></td>
    <td><font size=-1>
        Specifies the author of the class.
    </font></td>
<tr>
    <td><tt>@approval</tt></td>
    <td><font size=-1>
        Specifies who have given final approval of the
        documentation/implementation of a class.
    </font></td>
</table>
    ";

/*
 * How to divide into categories
 */
Odin32DBPodNaslov("How to divide into categories", "sdscat");

TekstBeg();
echo "
        The <tt>@cat</tt>-tag is really best illustrated with a short example:
        ";
TekstEnd();
CodeBeg();
echo "
class Foo
{
    /** @cat Datamembers */
    int bar;
    int xyzzy;

    /** @cat Methods */
    int fubar() const;
    void IRS(long money=ALLMONEY) const;
};";
CodeEnd();


/*
 * How To Document a Method
 */
Odin32DBPodNaslov("How To Document a Method", "sdsmethod");

TekstBeg();
echo "
        <i>(This is similar to the SDS Function Header.)</i>
        ";
TekstEnd();

/*  */
PodPodNaslov("An Example");
TekstBeg();
echo "
        There are basically four places where you can put documentation for
        methods. New documentation found for a method is added/appended to
        the existing documentation so it is quite possible to describe
        different aspects fo a method in different places. Please note that
        documentation is added as it is read.<p>
        ";
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:<p>
    ";
TekstEnd();
echo "
<table border=3>
<tr><td><b>Tag</b></td>
    <td><b>Description</b></td>
</tr>
<tr><td><tt>@desc</tt></font></td>
    <td><font size=-1>General description. (default)</td>
</tr>
<tr><td><tt>@return</tt></td>
    <td><font size=-1>What the function returns (Alias: @returns)</font></td>
</tr>
<tr><td><tt>@param <paramname></tt></td>
    <td><font size=-1>Parameters to the function.</font></td>
</tr>
<tr><td><tt>@status</tt></td>
    <td><font size=-1>
        Function status. See ";
AnchNaslov("Function State.", "functionstate", "");
echo "
    </font></td>
</tr>
<tr><td><tt>@time</tt></td>
    <td><font size=-1>Time complexity or estimated time use.</font></td>
</tr>
<tr><td><tt>@sketch</tt></td>
    <td><font size=-1>A sketch of the method, usually for design.</font></td>
</tr>
<tr><td><tt>@author</tt></td>
    <td><font size=-1>
        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.
    </font></td>
</tr>
<tr><td><tt>@remark</tt></td>
    <td><font size=-1>Any remarks.</font></td>
</tr>
</table>
        ";

require "07-ColumnTwoFooter.php3";
require "08-News.php3";
require "09-ContentsTitle.php3";

Odin32DBWriteContents();

require "10-EndOfContent.php3";
require "11-NetlabsContact.php3";

$Kada=date ("j M Y", filemtime(__file__));
require "12-OdinBanner.php3";

require "13-Closing.php3";

/* Profiling */
Odin32DBTimerStop($sPageTimer);
/* Profiling */

?>