----- Original Message -----
From: James Carpenter
Sent: Thursday, June 12, 2003 5:06 PM
Subject: CcDoc configuration for Doxygen for use with Symbian Series 60 code
Has anyone out there configured Doxygen for use with CcDoc style comments?
If so can you provide the various configuration files for doing so.
(I have looked closely at Doxygen in the past but I have never used it. I
remember that it supports custom tags and hence could be configured for
supporting most any markup.)
My interest is in generating documentation for Symbian Series 60 code. It
is obvious from example code supplied by Nokia that they are using some sort
of documentation generation system. Unfortunately, they provide zero
guidance in their SDK documentation telling me how to make use of the doc
tags their code is using. I once posted a question about documentation
generation on several of the Symbian discussion groups and it seems no that
knows the answer is talking (or reading the free discussion groups).
Furthermore I will need to figure out how to work the documentation system
chosen into the Series 60 build system. (For those not familiar Symbian,
Series 60 has a makefile generation system not unlike that found in Perl.
In fact the Symbian makefile generator is written in Perl.)
If anyone here can help me get past these problems quickly it will be
appreciated. I can't spend much time on this problem just now, so if I
can't set things up in a few hours I will have to postpone the documentation
effort. It seems to me the only way to make quick progress is to find
doxygen configuration files for the CcDoc tag style being used. Ideally
someone who is familiar with Symbian can even tell me how to quickly hook
this into the Series 60 build system. I will cross post this on the various
Symbian discussion groups.
For Symbian developers reading this I am pretty sure that one hooks a
documentation generation system into the Symbian build using the "Extension
makefiles" feature of the bld.inf file. Details can be found at Symbian OS
v6.1 Edition for C++ » Tools And Utilities » Build Tools Reference » bld.inf
file syntax » Extension makefiles in the Series 60 SDK documentation.
Even if no one can provide doxygen configuration files for CcDoc style
comments it should be possible to hook in CcDoc instead of doxygen. This is
less desirable because then one doesn't get UML diagrams.
The only mention of documentation generation systems I can find in the
Series 60 SDK docs is the following snippet found in Series 60>>Series 60
Examples>>Coding Conventions of the SDK docs.
Stylised comment blocks in the format described below should be inserted
into header files to help with automatic document generation. The convention
is generally that used by Together, JavaDoc and CcDoc. There should be a
separate comment block for each class, operation, and member variable
declared in the header file.
A comment block starts with a '/**' and ends with a '*/'. Each line starts
with an asterisk '*'. The basic format is:
Alternatively a shorter form can be used:
/** <BriefDescription> */
The <BriefDescription> should be an informal, one-sentence description of
the class, operation or member variable.
The <MarkUpTag> entries start with an @ sign and are the first things (after
the optional leading asterisk) on the line.
* A Rectangle object, which can be moved and rotated.
* @invariants iLength > 0;
* iHeight > 0;
* @semantics Construct a new rectangle
* at position ( aX , aY ),
* length aLength, height aHeight.
* @stereotype constructor
* @preconditions aLength >= 0; aHeight >= 0;
TRectangle( TReal x, TReal y, TReal aLength, TReal aHeight);
* Rotate operation
* @semantics Rotate this rectangle by aAngle degrees
* about its centre
* @stereotype modifier
* @preconditions aAngle >= 0; aAngle <= 360;
void rotate(TReal aAngle);
* Absolute move operation
* @stereotype modifier
* @semantics Move this rectangle to position ( aX , aY ).
void move_to(float x, float y);
/** The x position of this rectangle*/
/** The y position of this rectangle*/
/** The length of this rectangle*/
/** The height of this rectangle*/
for your time and effort.