SDOC Information

Table of Contents:

The SDOC XML Format

Converting CSF to SDOC

ModSpec Examples

1. The SDOC XML Format

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:

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.