ISDM

ISDM - The iSDocMarkup language

Introduction

The ISDM syntax has been designed to help ease programmers documenting their applications and is essentially a list of symbols whose elements must be inserted at the beginning of a comment to mark the comment as documentation-related and a list of rules which must be applied when writing in-source documentation.

The syntax itself is pretty easy to use and remember, as it relies on a small group of symbols used as markup tokens.

In addition to the syntax, the specification includes a set of attributes and operators (such as the 'default' operator) which can be included into the documentation to empathize some aspects of the code that is being documented.

Syntax

The ISDM syntax is strict and must be used as follow:

[(spaces/tabs/newlines)]{COMMENT-BEGIN}{ISDM-TYPE-SPECIFIER} [ARGUMENTS]
[(spaces/tabs/newlines)]{ISDM-DESCRIPTOR}:
[(spaces/tabs/newlines)]{PROPERTY-CONTENT}
[...]
[(spaces/tabs/newlines)]{COMMENT-END}

Block-form syntax

Where {} means 'compulsory', and [] means 'optional'.

ISDM syntax also allows a quicker form:

{COMMENT-BEGIN}{ISDM-TYPE-SPECIFIER} {DESCRIPTION} {COMMENT-END}

Quick-form syntax

Here is a C++ example:

/** 2
    iSDocMan: ice Source-code Documentation Manager
    Copyright (C) 2011 Alfredo 'IceCoder' Mungo

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

/*! Dummy function */
void dummy();

/*!
    DESCRIPTION:
        The Main function.
    ARGUMENTS:
        argc: integer
            The number of command-line arguments.
        argv: char**
            The command-line arguments.
    RETURNS: int
        The value to be returned to the OS.
    NOTES:
        1) This function does absolutely nothing.
        2) These are test notes.
        3) Ok.
*/
int main(int argc, char **argv)
{
    return 0;
}

Example code

In the following example, we mark the license (with an asterisk), and two functions (with an exclamation mark): dummy() and main().

The dummy() function uses the quick form, while the main() function uses a block form.

Inside the main() documentation you can note the ARGUMENTS and RETURNS statements, which include a type definition.

As you can see, the syntax is straightforward.

Please refer to the [Descriptors] page to find which descriptors are available.