Getting Started

Which files are important to comment
DocJet extracts comments from source code and organizes them into documentation. To begin with, using comments as the basis of the produced documentation gives programmers the ability to use familiar tools, such as their program editor, to enter the documentation. Since these comments are put alongside the object which they document, it is easy to maintain consistent documentation. For example, if a programmer removes a function, the comment can, with no additional effort, be removed at the same time.
DocJet understands most commenting conventions, introduced with any of the comment styles supported by the source language. No special thing is required for a comment to be recognized as a DocJet comment, boxed comments are accepted as well as walled and plain. DocJet understands most commonly used commenting conventions.

Which files are important to comment

Interfaces that should be used by others, must be commented in such a way that documentation can be generated for them. The same is valid for both C/C++ and Visual Basic.
If you want to generate documentation for a design document, you must comment it in such a way that the comments are interesting to have in a design document.
When generating documentation with DocJet, it looks for comments for all external objects, including external functions, external variables, macros, classes, structures, typedefs, methods and members. It also wants all function and method parameters to be documented.

General about Comments

DocJet understands most commonly used commenting conventions, introduced with any of the comment styles supported by the source language.
Some of these general comment examples are described in C++, but the same is valid for Visual Basic.
Note, DocJet recognizes comments separated by blank lines as different comments, but back-to-back comments are considered as parts of a whole command. For example, this is considered one comment:

 
// Description:

//    This is what it does.
//
// Return Value:
//    This is what it returns
 
But this is considered two different comments:
 
// Description:
//    This is what it does.
// Return Value:
//   This is what it returns
 

This distinction is important because, in most cases, the second comment will be taken to be the description of the object, and the first comment will be considered spurious and ignored.

The DocJet keyword {secret} can be used to hide comments from the DocJet document generation, see the DocJet help file.

Comments before Objects

In general, comments must be placed directly in front of the object that they are documenting. They must be continuous - for instance:
// Description:
//   This is what it does.
// Return Value:
//   This is what it returns
Foo Fubar( const Bar& x )
{
...
 
"Return Value: This is what it returns" will be the comment associated with the function "Fubar".

Comments after Objects

Function Arguments

Function arguments are one of two exceptions to the rule that comments must precede the object being documented. DocJet make this exception because most people that comment arguments, do like this:
//
// Description:
//   This function converts a Foo to a Bar
//   under a given ruleset.
//
// Return Value:
//   An object of the Foo built from x and rules.
//
Foo Foo2Bar(
const Bar& x, // This is the object to
              // be converted to a Foo.
const ConversionRules& rules // These
                             // are the rules under which
                             // the conversion is performed.
  )
{
...
}
In the event that one of your parameter names is exceptionally long, you can put your comment on the next line, that is, the following would be legal as well:
 

Foo Foo2Bar(

const Bar& x,
               // This is the object to be converted to a Foo.
const ConversionRules& rules
               // These are the rules under which
               // the conversion is performed.
)

Structures

The next exception to the rule that comments precede objects is in structure member lists. If you have a structure that looks like:

struct Slope {
int rise;
int run;
};
 

You can comment it like this - noting that the start of the comment must be on the same line as the semicolon of the object declaration being commented:

struct Slope {

int rise;   // This is the number of inches
            // that the slope increases or
            // decreases over the run.
int run;    // This is the distance that is
            // traversed. It is usually
            // 12 or 36, but can take other
            // values in certain cases.
};
 
In Visual Basic, the same thing can be done like so:
Pub BigStuff As Object      'This points to the
                            'big stuff
Pub LittleStuff As Object   'This points to
                            'the little stuff
 

DocJet accept this form of comments because it is often used. When the description is long, the following commenting style will increase readability:

struct Slope

{
    // This is the number of inches that the slope increases
    // or decreases over the run.
    int rise;
 
    // This is the distance that is traversed. It is usually
    // 2 or 36, but can take other values in certain cases.
    int run;
};

C++

DocJet has a strong understanding of C++, which allows it to do a number of things that make output richer and input easier for the programmer. First off, DocJet understands virtually any sort of commenting style - be it boxed, entered with "//", "/*", or whatever.
Secondly, DocJet understands declarations well enough that the comment for an object can be entered wherever an object is declared. This allows you the flexibility of putting comments in the header file or the implementation file or another file altogether. Because of its understanding of C++, programmers need not bother themselves with describing things like class relationships, membership, overloading. Further, DocJet goes so far as to understand parameter lists, allowing comments to be entered that describe each argument to a function or method.
Templates for how to write comments are found in See Templates , including a file header which should be included in every source code file.

How to comment classes and interfaces

COM Interfaces and IDL

DocJet processes IDL files just like C++ files, so you comment IDL files the same way you comment C++ files (up to and including boxed comments and commented arguments). The only thing to note about the commenting conventions is that DocJet's IDL scanner will accept comments for the interface before the header (the [uuid( ...) part or just before the word interface). IDL interfaces are treated just like C++ classes, and everything else (typedefs, structs, enums, etc.) are handled exactly like their C++ counterparts.
To be able to comment your IDL interfaces within the C++ code that implement them, a rewriter DLL is used when generating the documentation. When commenting your code, you have to have a special keyword in the IDL part:
// IDLMAP:IInterface1=CInterface1
You still have to write the comments for the interfaces, coclasses, and type libraries within the IDL, this keyword just helps out with the methods. When you use the keyword, you must write all the comments for the methods in the C++ code, and not comment the methods in the IDL file. If you have a comment in the IDL file, only this comment will be taken, and nothing from the C++ file. DocJet does not combine the comments, it just takes the IDL file or the C++ file.

The keyword helps the scanner to the fact that the methods listed in "IInterface1" are implemented in "CInterface1". Whenever the rewriter DLL sees a method of CInterface1, it looks for a corresponding method within IInterface1. If there is one, and the method of IInterface1 has no comment, then the comment from the CInterface1 method is used as the comment of the method of IInterface1.

Your argument names in the IDL file need to match the names you use in your C++ file, they must for example be spelled in exactly the same way.

Example:

 

Comments in the IDL file:
/////////////////////////////////////////////////////////////////
//
// IDLMAP:IAfwClassIOHandler=CAfwClassIOHandler
// Description:
//   The IAfwClassIOHandler interface...
//
//////////////////////////////////////////////////////////////////
[
  uuid(CBBBA622-2E80-11D1-BD42-000000000000),
  helpstring("IAfwClassIOHandler Interface"),
  pointer_default(unique)
]
interface IAfwClassIOHandler : IUnknown
{
  [helpstring("method SetFile")]
  HRESULT SetFile(
    [in] const wchar_t* fileName,
    [in] BOOL readFlg);
};
Corresponding part in the C++ file:
///////////////////////////////////////////////////////////////////////////////////////////
//
// DESCRIPTION:
//   The function associates a file with a IO handler object. The file
//   is specified with a file name.
//
// PARAMETERS:
//   fileName - [in] File name to be associated with IO object.
//   readFlg - [in] Control is read (TRUE) or write (FALSE) is desired.
//
// RETURNS:
//   S_OK - The function completed successfully
//   E_FAIL - The function failed, the file could not be read
//   or written.
//
// REMARKS:
//   A file has to be associated with the AfwClassIOHandler COM object, which is done
//   through the SetFile method, in order to be read (parsed) or written.
//
///////////////////////////////////////////////////////////////////////////////////////////
STDMETHODIMP
CAfwClassIOHandler::SetFile (const wchar_t* fileName,
                             BOOL readFlg)
{
...
}
An example of generated documentation for the SetFile method is found in See Example of generated HTML documentation . The generated documentation includes both parts from the C++ and the IDL files. The shown documentation is in HTML format, based on the AdvantHTML template, see See Document Generation .
Figure 2-1. Example of generated HTML documentation
 

General Class Comments

Put the description of the class in a general comment block in the header file that declares the class, like:
//
// A Foo is a thing...
//
class Foo : public Thing
{
...
}

How to comment functions, methods, operators

The recommended way to comment a function/method in the implementation part, is like:
/////////////////////////////////////////////////////////////////////////////////////////
//
// DESCRIPTION:
//   When a file is to be written the Store method is used. The method will create
//   a new temporary file, write data to it and rename it to the file name specified
//   in the SetFile method.
//
// PARAMETERS:
//   object - [in] Name of the object suppling, holding parse information.
//   openStruct - [in] Indicates a style of reading parse information without
//   braclets.(TRUE)
//
// RETURNS:
//   S_OK - The function completed successfully
//   E_FAIL - The function failed, the file could not be read or written.
//
// REMARKS:
//   The Store method completes the association between a file name and
//   the AfwClassIOHandler, the handler object is then terminated only to be reused for
//   other reading or writing operations.
//
///////////////////////////////////////////////////////////////////////////////////////////
STDMETHODIMP
CAfwClassIOHandler::Store(
  AfwClassIOObject* object,
  BOOL openStruct)
{
...
}
Note: The commenting sections for RETURNS: and REMARKS: must not contain any Tabs, and should not start later than the 7th position of the line. If the comments are indented more, the generated documentation will show the text for these comments in the Courier font instead of Times Roman.
The best is to place all comments for a method in one place, preferably the implementation part. Do not mix the comments in both the header file and the implementation file! DocJet usually does not combine comments, and it can take one comment and skip the other.

When commenting structures, class members etc., the normal C++ comment is used:

int dotIndex; // index where the dot is found

Method Parameters

Note, that function/method parameters described in an IDL file, or header file, need to have exactly the same name and spelling as in the implementation file. C++ itself does not require this, it works with the type and sequence. If there is a spelling error in the parameter description between the header/IDL file and implementation file, this will confuse DocJet, and not generate a correct documentation. You get warnings when generating the documentation.

Example of a non-proper description:
Class description:

class A

{
void DoSomething(int otherName);
};
Class implementation. Note, the different spelling of othername:
//...
// PARAMETERS:
// othername - another name
//...
////////////////////////////////////////////////////////////
void A::DoSomething(int othername)
{
...
}

Placing comments with declarations or implementations

DocJet understands C++ better than you might think. It understands structure membership, and, in fact, can understand embedded classes, structures, methods, and pretty much anything related to object declaration.
DocJet understands that the same object can be declared in one spot and implemented in another. For instance, if you have an external function that is declared in a header file and implemented in another file, you can put your comment in front of either one. When there are comments for a class method both in the header file and the implementation file, the comments in the implementation file will be taken by DocJet.
Structure and class members are the only kind of object which must be commented in-place. Currently DocJet ignores all comments not associated with an object declaration, and there is no way to declare structure/class members except inside the structure/class definition.

Visual Basic

Templates for the comments are found in See Templates .

File Header

To have a description of each Visual Basic class, form, and module, each file header starts with a description line in the file header, followed by a blank line.
After the description the file header includes comments describing the author, and version information. To have version information included in each file, RCS keywords like "$Id$" and "$Log$" are included.
You can have a problem, if your Visual Basic file starts with comments including the RCS keywords, instead of the description followed by a blank line, and you do not want the version information to be included in the generated documentation. To get around this make sure the version part of the comments in the beginning of each file is first of all in one piece with no empty lines in between, and that it ends with a real code that does not need to be commented. It must be the Option Explicit statement that is commonly used.

An example of Visual Basic comments is found in Chapter See Visual Basic Classes, Forms, Modules, and Controls .

Functions

A Visual Basic function/subroutine are commented in the following way:
'--------------------------------------------------------------------
'
' DESCRIPTION:
'   Calculates the real word length.
'
' PARAMETERS:
'   ZeroPos - Position of the found zero in array
'
' RETURNS:
'   The calculated word length
'
' REMARKS:
'   This method gets index for found zero in array and
'   and muliplies every number after the zero with 255
'   and addes to a SUM and repeats untill the last
'   number before a zero is found. That one is only
'   added to SUM. The sent index is set to the next
'   index after the second found zero.
'
Private Function GetLWordLength(ZeroIdx As Long) As Long
...
Note: The commenting sections for RETURNS: and REMARKS: must not contain any Tabs, and should not start later than the 7th position of the line. If the comments are indented more, the generated documentation will show the text for these comments in the Courier font instead of Times Roman.
When commenting an object or variable, use the normal commenting syntax. For example:

Private IsLogMessageAdded As Boolean ' if a log message is added

 

Visual Basic Classes, Forms, Modules, and Controls

In Visual Basic, there is no explicit syntax for the class or form itself. To enter comments for these things, put the comment as the absolute first thing in the file and make sure there is a blank line between the last line of the comment and the next comment or object declaration.
In the example below the first line comment will be used as a main description for the control in the generated documentation, the other comments will not at all be included in the generated documentation.
Example:

' Show versioned files in a listview and provides rcs commands.

' FILE     SdeRCSviewControl

'
' $Id: SdeRCSview.ctl,v 1.2 1998/05/15 07:08:51 icrnkovi Exp $
'
' AUTHOR     SEIPR/LKD Ivica Crnkovic
'
' All rights reserved. Reproduction, modification, use or disclosure
' to third parties without express authority is forbidden.
' Copyright ABB Industrial Products, Sweden, 1998.
'
' HISTORY:
'
' $Log: SdeRCSview.ctl,v $
' Revision 1.2 1998/05/15 07:08:51 icrnkovi
' Add comments according to Vb Style Guide and DocJet standards
'...
'
' ABSTRACT
'
' properties
'------------
' WorkFilesView - True, False - get/set Work view
' FileListView - ListView Control incapsulated in the control
' CurrentDir - the node current directory
' FileFilter - set filter for the files
'
' methods
'----------
' ListNodeFiles - lists nodes versioned or working view
'
' Events
'-------
' ItemClick
' MouseUp
'
Option Explicit
Private Const WorkViewTitle = " View: Working Files" ' current view title
...