Documenting a model element

The Objecteering C++ Developer GUI can be used to conveniently enter and modify brief summary and detailed documentation notes directly from the "C++" tab of the auxiliary window and from the dedicated tab of the C++ edition dialog boxes.

To document a model element, simply select it and enter the associated documentation text in the "Summary" and "Documentation" fields of the "C++" tab of the auxiliary window.

Objecteering C++ Developer translates the contents of notes as follows:

· Notes entered in the "Summary" field are translated into the "\brief" doxygen tag. Summary notes should contain only one paragraph.

· Notes entered in the "Documentation" field are translated into ordinary doxygen comments. Description notes can contain any number of of paragraphs and doxygen tags.

Documentation for UML operation parameters is automatically grouped with the operation doxygen comment.

Figure 69. The "Summary" and "Documentation" fields in the "C++" tab of the auxiliary window

The "C++" tab of the auxiliary window is very practical for the quick entry of single line summary notes, but less convenient for complex multi-line documentation notes.

For optimal comfort and convenience, you can enter multi-line documentation notes in the "Description" field in the "Documentation" tab of C++ edition dialog boxes (Figure 70).

Figure 70. The "Documentation" tab of a C++ edition dialog box

The "Documentation" tab is available in all C++ edition dialog boxes.

Documentation can also be entered without using the Objecteering C++ Developer GUI. You can enter summary notes in "comment" notes and documentation notes in "Cxx.Doc.Doxygen" or "description" notes.

For example, we want to document the "TaskWindow" class in our application model. We select the class, quickly enter a summary of the class in the "C++" tab of the auxiliary window, and then continue by entering the detailed description in the class C++ edition dialog box. In the description note, we use several doxygen tags to specify cross-references and "to do" notes (Figure 71).

Figure 71. The description entered in the class C++ edition dialog box for the "TaskWindow" class

Objecteering C++ Developer produces the following code for the "TaskWindow" class, where the summary and documentation notes are injected as a doxygen comment with automatically generated "brief" tag and our tags.

//includes for used library types

#include <cstringt.h>

#include <afxwin.h>

#include <afxtempl.h>

#include <afxcoll.h>

//automatic includes (friends, associated classes, etc)

#include "MyPlanner/CWnd.h"

#include "MyPlanner/ITaskView.h"

#include "MyPlanner/Task.h"

namespace MyPlanner

{

/**

\brief

Task visualization window

The class is used to graphically represent Task data.

Namely, the class is used to render:

- task information

- task status

- subtasks

- resources

\todo

Implement message handlers

**/

class TaskWindow : public CWnd, public ITaskView

{

//...

private:

CString displayTitle;

public:

CDC dc;

//associations

public:

Task* task;

CMap<CString,CString&,CBrush,CBrush&> brushResource;

//operations

public:

TaskWindow();

TaskWindow(const TaskWindow& value);

TaskWindow& operator =(const TaskWindow& value);

~TaskWindow();

void formatDisplayTitle(std::string& FormatStr);

CDC getDc();

afx_msg int OnCreate(CREATESTRUCT* lpCreateStruct);

//non-modeled members

protected:

//modifiable zone @16224@30671900:2404@T

DECLARE_MESSAGE_MAP()

//modifiable zone @16224@30671900:2404@E

};

}