SDOC has just recently been revised due to the revision of CSF. SDOC is the documentation format of SDS, and more or less use the same mechanisms as CSF, but adds a few other constructs specific for documentation. "SDOC modules" are specified by the ModSpec format which currently only is documented by an example. SDOC-tools also adhere to preferences specified in a preference-file.

Please Note: A csf2sdoc tool is allowed to add values to info-fields which most CSF-tools might not understand.

New/changed/removed constructs

SDOC is basically like CSF, except that it adds two constructs; the module and the category. The module is a documentation construct which allows one to group other constructs into modules based on various criterias. The modules are defined in a specific xml-format; ModSpec;, and then CSF-data is translated into SDOC-modules using those specifications. The category construct allows one to split up classes and modules into different parts for presentation. Categories are also specified with ModSpec.

SDOC basically copies the raw CSF-data into new locations in SDOC but doesn't use all parts with the same vigour. SDOC also adds a new field to most constructs, the doc-field which basically serves the same purpose as the info-field but contains documentation.

<doc type=doc_type>
   <text>... text ...</text>
</doc>

One important part is removed from CSF; comments. These are if applicable, translated into documentation (the doc elements).

2. Converting CSF to SDOC

This is usually an unproblematic job. Check the csf2sdoc tool and it's command-line options. However, it does work in a certain manner which might be interesting to know about.

Documentation from Source Code

If your front-end is much to brag about, it also gets you the comments in the source code and places them in the CSF-file. csf2sdoc will filter out all comments and if the text begins with an asterisk '*' (at least for C++ and Java) it will try to find the construct it belongs to and add the info to the appropriate DOC-field. Ordinary comments are removed.

Documentation from INFO-fields

Some languages are constructed more intelligently than others and contain documentation as part of the constructs. These should be placed in appropriate INFO-fields which the converter will move to appropriate DOC-fields for the SDOC-format.

Documentation from ModSpec

When arranging modules and categories with the ModSpec format, one can add several info-fields. These should be moved to appropriate DOC-fields during conversion. No rules are made here yet, though.

Documentation Keywords

More info on documentation-keywords will be added later. Some keywords will have side-effects, like creating a category.

Keywords that probably will be supported:

approval - who has approved the object in question
author - who has written the object in question
desc - the usual description
dstruct - describes a data-structure
equiv - an "equivalent to"-field
memo - see oneline
oneline - a one-line description, e.g for index
param - for docs about parameters
remark - caveats and helpful remarks
returns - for functions; description of the return value
seealso - a link-simplifier which links to other objects
sketch - a sketch of a function or class or construct
space - estimate on space use, complexity, etc
time - estimate of time use, complexity, etc
version - information about the version of the object

3. ModSpec examples

SDS does also support C and allows one to document C-like modules. It's highly configurable and support three ways to find an object's module and category. It is best explained with an example, here with modules.xml:

<?xml version="1.0"?>
<!DOCTYPE modules SYSTEM "modules.dtd">

<!-- Example of a module for a whole directory (recursive) -->
<modules>
  <module name="libc" fullname="GNU C-Library">
    <info type="memo" value="The important c-library"/>
    <info type="desc" value="Don't leave home without this library"/>
    <info type="version" value="2.0.7"/>
    <info type="organisation" value="FSF"/>
    
    <scope>
      <dir>/usr/include</dir>
      <dir>/usr/lib</dir>
    </scope>
    
    <category name="Stdio">
      <desc> This is stdio...</desc>
      <scope>
        <file>/usr/include/stdio.h</file>
      </scope>
    </category>

(.. snip categories.. see modules.xml ..)        
    
    <category name="C++">
      <desc> This is GNU C++ </desc>
      <scope>
        <dir>/usr/include/g++</dir>
      </scope>
    </category>  
</module>

<!-- Two familiar examples for gtk/gdk programmers which use prefix. -->
<module name="GTK">
  <scope>
    <prefix>gtk</prefix>
  </scope>  
</module>

<module name="GDK">
  <scope>
    <prefix>Gdk</prefix>
    <prefix>gdk</prefix>
  </scope>  
</module>

<!-- Example of module with specified files -->
<module name="Hummingbird">
  <scope>
    <file>tests/hum.h</file>
    <file>tests/hum.cpp</file>
  </scope>  
</module>

</modules>

This is hopefully understandable, a module is defined over a scope (and first come is first served) and the categories (or modules within) defines their scope with respect to the scope of their parent. Hopefully directory, filename and prefix should be enough for most code.