Documentation using Doc++ - Kansas State University



Documentation using Doc++

Introduction

DOC++ is a documentation system for C/C++ and Java. It generates HTML output for sophisticated online browsing of your documentation. The documentation is extracted directly from the C++ header or Java class files.

The idea of DOC++ is to provide a tool that supports the programmer for writing high quality documentation while keeping concentration on the program development.

There are two types of comments the programmer wants to distinguish. One are comments he/she does for remembering some implementation issues, programming logic, etc. While the others are comments for documenting classes, functions etc. so that any API user would be able to understand the interfaces later on. In DOC++ this distinction is done via different types of comments. Similar to `JavaDoc', documentation comments are of the following format

• /** ... */

• /// ...

Where the documentation is given in”...''

Such comments are referred to as DOC++ comments

Inserting DOC++ Comments

1. Add triple slashes before each function, variable, class, define etc which you want to be documented

/// “….”

You can add appropriate comments in place of “….”

2. If you intend to write more than one line of documentation, succeed this line with a comment like

  /**

….. ...

    */

Docifying your source code

There is another application called “docify” which adds comment initializers to the uncommented file.

The following command inserts /// before each function, variable, class etc.

docify  

Class before “docifying”

Class after “docifying”

You can now manually add the required comments at the appropriate positions.

Getting started

Download lab.cpp.

Download the file in a separate directory and generate the documentation files by using the following command at the command prompt

> doc++ --dir html lab.cpp (Double dash before dir)

The tool will create a html directory and place all the generated html document files in it.

To be able to see the private variable / method listing use --private option

> doc++ --dir html --private lab.cpp (Double dash before dir and private)

NOTE : You can run the same command without the –dir option. In that case the generated files will be in the same directory from where you ran the doc++ command.

Open the index.html to start browsing through the documentation generated.

Today’s Assignment

1. Document the hash.cpp file present at cis.ksu.edu/~vikas/hash.cpp and show it to the TA.

CIS540/543 Project Documentation

For documenting your projects you MUST have the following

- A short description for each class and its attributes.

- Each method should have a short description of what it does, the parameters it takes and its return type

-----------------------

/// Class Person, The Base Class

class person

{

protected:

/// This variable stores the first name of a person

char* fname ;

/// This variable stored the last name of a person

char* lname ;

public :

/// The constructor for the person class, it allocates memory for name.

person()

{

fname = new char[15];

lname = new char[15];

}

class person {

private:

char *name;

public:

person();

void setname(char *newname);

char* getname();

};

///

class person {

private:

///

char *name;

public:

///

person();

///

void setname(char *newname);

///

char* getname();

};

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download