Last release: v1.1 of May 2006
Makedoc is a GUI-based HTML documentation generator for C, C++, and Qt-enhanced C++, which focus on simplicity of use and source code independence.
It intends to provide a tool that relieves the developer from acquiring new technical skills and bringing source code adaptations for specific tools. Makedoc should make it possible to create shareable documentation for most source codes without modification and within minutes, simply by opening the GUI, entering the path(s) to its source code files the first time, and clicking on the generation button.
Makedoc is free for use (no cost) when not used within a company or any organisation in the scope of its business operation. Check this link for further information.
Makedoc has the following features:
Makedoc provides support for the Qt library as follows:
Makedoc is a command line application whose functions can be controlled through option switches. The executable file is makedoc[.exe]
However, the most common and convenient way to use and control it is to use its graphical front-end GFE Makedoc of which you see a screenshot above. The executable file is gfemakedoc[.exe].The graphical front-end makes it straightforward to control all functionality of makedoc and run it.
Moreover, it allows to save your settings for each of your individual documentation generation project (.mdoc files). The project files (.mdoc) used to generate the online documentation of LLOOP (C++) are provided as examples with Makedoc.
Use the entry panel at the right to enter the necessary configuration. Each entry is fully documented in the leftmost window when you move the mouse over it.
Multiple values in an entry must be separated by comas.
Finally, click on the run button 
to start the generation.
When a class of your project refers to another class of the same project, eg. in a function prototype or by inheritance, Makedoc will attempt to generate a link to the matching documentation. However, the link will actually be created only if that documentation was generated before and is already available on the disk.
Therefore, the first time you generate the documentation for your set of classes, you should always run it a second time. This is also true whenever new classes need to be documented or whenever links seem to be missing.
Click on the browser button to browse the documentation index
Click on the hyperlink which is generated in the output window to browse a particular class documentation
Note: you have to ensure that a valid browser executable name is provided for the 'Browser' parameter of your generation project. By default, 'konqueror, netscape, firefox' is set under UNIX and 'explorer.exe' is set under Windows.
The scope of the generated documentation can be controlled through some basic parameters in order to address various needs depending of the sought level of documentation or the intended audience:
If all or some of your classes are defined in header and implementation files that have the same base file name, regardless of extension and letter case, Makedoc will be able to associate those corresponding files to generate the matching class documentation. In that case, only the path(s) of the directory(ies) from where to search the files need(s) to be provided inside the "Search path(s) for source files" entry of the graphical control panel.
In all other cases, each individual header and matching implementation file have to be provided inside the "Explicit source file(s)" entry.
The intend of Makedoc is to keep source code formatting constraints at a minimum. The following formatting rules stem more from common and wide-spread practices than from an imposed tool-specific constraint:
4. How to format the source code
Comments Setup
| Class description | the description of a class must be provided in a C or C++ comment preceding the class definition in the header file (.h, .H or other). |
| C source files description | the first C comment found in the C source header file (.h, .H or other) stands for the description of the C source files. |
| Function description | the description of a function must be provided in a C comment preceding the function implementation in the implementation file (.c, .cpp, C. or other). |
There is no constraint on how the comments for classes or functions are written. Makedoc ensures the following text processing in both cases:
Beside these simple rules, the following optional extra features are also available:
| eg: | Provide code examples which will be highlighted in raw formatted text (<PRE> tag in HTML). Code examples must be preceded by a line containing the special keyword eg: or @eg. Code example ends at the next empty line or the end of the comment. |
| see: | Provide prototypes of functions for which links will be created in the description. References to function prototypes must be preceded by a line containing the special keyword see: or @see. Function links ends at the next empty line or the end of the comment. |
| secondary: | A class can be qualified as "secondary" by specifying the @secondary markup anywhere inside the class comment. In that case, the class will be listed in the index of secondary classes, apart from the main index. This allows to improve greatly the guidance of the index which highlights key/important classes separatly from less useful ones. |
Below are given some very basic examples of class and function comments. A more comprehensive example showing a typical use is given along with the actual generated documentation in the next chapter.
/**
* This is a sample class description.
*/
class SampleClass
{
public: Sample();
};
or:
/* This is a sample
class
description
*/
class SampleClass
{
public: Sample();
};
or why not:
// This is a sample class
// description.
class SampleClass
{
public: Sample();
};
/**
* This is a sample function description.
*/
SampleClass::SampleClass()
{
}
or:
/* This is a sample
function
description
*/
SampleClass::SampleClass()
{
}
The following sample makedoc project files (.mdoc files) have been used to generate the sample documentation and are provided in the projects directory of the makedoc package.
| universal.mdoc | Documentation of LLOOP component classes with custom documentation style |
| universal-qt.mdoc | Documentation of LLOOP component classes with Qt documentation style |
| gsp.mdoc | Documentation of gsp namespace classes (LLOOP) with custom documentation style |
| gsp-qt.mdoc | Documentation of gsp namespace classes (LLOOP) with Qt documentation style |
| ini.mdoc | Documentation of ini file parser classes with custom documentation style |
| ini-qt.mdoc | Documentation of ini file parser classes with Qt documentation style |
| example.mdoc | A project that contains all aforementioned projects, allowing automatic generation of all examples |
Among the documented classes, there is notably the class String which is used here as example for showing typical source code formatting and their matching generated documentation.
The class String is described in a comment preceding the class definition as shown below:
[...]
/**
* This class offers a set of low and high-level operations for safe
* and convenient handling of character strings, including commonly used
* operators (==,=...) and conversion functions to numeric types.
*
* The strings are managed like conventional C-style null-terminated ASCII
* strings (char *). Input or output const char* values are therefore
* always assumed to be null-terminated. If not so, the results are
* undefined.
*
* The cast operator to const char* is useful for getting the raw C-style
* string.
*
* Some of the functions are also compatible with the handling of binary
* buffers, even if these buffers may contain null or non-printable chars.
* This peculiarity is always documented for the matching functions.
*
* This class is especially optimised for high performance and combines
* internally static and dynamic memory buffering. A string instance always
* holds a deep and private copy of its string. String instances never share
* memory buffers.
*/
class UNIVERSAL_DLL String
{
[...]
Click here to view the matching documentation generated for this class description.
The function String left(unsigned int) const defined within the class String is used to show how a description for a function can be provided. This function is described in the following comment preceding the function implementation:
/* ------------------------------------------------------------------------- */
/**
* Returns the uLength leftmost chars.
*
* If uLength is greater than the actual string length, an empty string
* is returned.
*
* Otherwise it is equivalent to mid(0, uLength)
*
* eg:
* String s = "Welcome home";
* String s2 = s.left(7) // s2 = "Welcome"
*
* see:
String mid(unsigned int uPosition, unsigned int uLength) const ;
String right(unsigned int uLength) const ;
String substring(unsigned int uPosition, unsigned int uPositionEnd) const ;
String operator()(unsigned int uPosition, unsigned int uLength) const ;
*
*/
String String::left(unsigned int uLength) const
{
return mid(0, uLength);
}
Click here to view the matching documentation generated for this function description.
A development often involves external APIs which are developed by third parties. The Microsoft MFC classes or the Trolltech Qt classes are examples of such component libraries.
Most of the time, a documentation for these APIs is also provided by their supplier. Moreover, their source code may not always be accessible. Therefore, it is useful that the generated documentation can also provide links to any existing documentation whenever a class, type or function external to your own development is referred to there.
The next paragraph gives an example of a typical use of an external API. Following, it is explained how to integrate references to external classes.
Let suppose you have defined a class This class inherits from the Qt class Now, a documentation for these respective Qt classes already exists, and it could be useful if you could jump to this documentation from the References to external class documentations can be integrated during generation simply by providing an ini file where the properties of the first section (the name of the section does not matter) give the names of the external classes and their values the file paths or URLs to their matching documentations.
For example, the following ini file could be used to integrate references to the QWidget and QString classes mentioned in the previous source code sample:
Note that the references given here are platform-dependent since they are local paths on a UNIX system. If you intend to remain platform-independent, it is therefore recommended to put URLs rather than local paths like shown below (the URLs are not valid and are only used for the sake of the example):
Finally, the path of the ini file, i.e. here "qt lib.mdocexp" for instance, must be specified for the "External References" property in the control panel of the graphical front-end:
Note: qt lib.mdocexp is part of the Makedoc package. The following list intends to give an exhaustive overview of all source code information which can be documented regardless of actual configuration parameters. For C++:
For C:
The following features are common to C and C++:
Notes:
When there are both C and C++ files, both information are groupped together, notably with regard to the global index where classes and C header files will be listed together.
The style of the generated documentation is managed using CSS which allows to control the form of the documentation independently of its content, in a standard, open and customisable way.
The following CSS file is provided and always proposed by default when a new project is created:
Additionally, the following CSS file is also provided for generating qt-like documentations. This file must be used along with the matching HTML templates.
The style classes which are available for the control the style of the generated documentation are the following:
The documents are generated from HTML template files and are therefore easily customisable. The following templates are provided and set by default when a project is created:
Additionally, the following templates are provided and can be used to generate qt-like documentations:
Customisation:
Conventional HTML comment markups like
Source code documentation is often a costly and painful process, yet critical for maintenance and sharing purposes where design and sharing of re-usable components are becoming a strategic requirement.
The documentation work itself is unavoidable and remains a time-consuming task which yet does not put up any technical barrier. However, developers are often discouraged from putting more efforts towards generating high-level documentations from those source codes, to bring and share the essential information in a form readable by anyone.
Why ? Simply because the available tools are often off-putting and require too much additional skills and time to use them, while imposing too constraining rules on source code formatting.
Makedoc can be downloaded for each supported platform listed below by clicking on the matching link:
6. References to external class documentations
Introduction
Example
MyWidget as follows:
#include <qwidget.h>
class MyWidget : public QWidget
{
public:
QString getName();
};
QWidget and defines a method getName() which returns an instance of the Qt QString class.
MyWidget class documentation generated by Makedoc.
How to integrate references to external class documentations
[qt]
QWidget = /usr/share/doc/qt-devel-3.3.3/html/qwidget.html
QString = /usr/share/doc/qt-devel-3.3.3/html/qstring.html
QButton = /usr/share/doc/qt-devel-3.3.3/html/qbutton.html
[qt]
QWidget = http://www.ersa-france.com/intranet/doc/qt-devel-3.3.3/html/qwidget.html
QString = http://www.ersa-france.com/intranet/doc/qt-devel-3.3.3/html/qstring.html
QButton = http://www.ersa-france.com/intranet/doc/qt-devel-3.3.3/html/qbutton.html
7. What information is documented
8. CSS style files
body_doc style of class documentation body body_index style of documentation index body body_source style of source code view body index_class_table style of table containing the class index index_class_item style of class names in the index index_secondary_class_item style of class names in the secondary class index index_class_item_letter style of index letters index_secondary_class_item_letter style of secondary class index letters func_title style of function prototype in function documentation func_qualifier_slot style of qt 'slot' qualifier at the right of slot function prototype in function documentation func_qualifier_visibility style of C++ visibility qualifier ('private', 'protected'...) at the right of function prototype in function documentation func_qualifier style of any other function qualifier ('virtual', 'static'...) at the right of function prototype in function documentation see style of a see reference eg style of a given example index_inherit style of inherited classes indexes index_var style of variable entries in variable indexes index_var_name style of variable names in variable indexes index_type style of type entries in type indexes index_func style of function entries in function indexes index_func_arg style of function argument names in function indexes table_index_virtual_func only for indexes arranged as tables: style of virtual function name cells in function indexes. By default it is grey table_index_pure_virtual_func only for indexes arranged as tables: style of pure virtual member function name cells in function indexes. By default it is green table_members_index only for indexes arranged as tables: style of index table table_member_index_item only for indexes arranged as tables: used by default to remove the margin before the point in the first cell table_member_index_item only for indexes arranged as tables: style of member index titles (eg 'Public Function'). Used by default to increase margins around the title 9. HTML templates
In the most common and simplest case you have nothing to do more than using either of these template sets. However, in advanced uses, these templates can be customised to your own preferences, language or company quality system.
<!-- index_name --> are used as keywords for the content replacement during generation. Therefore, the templates can easily be customised from your usual HTML editor. Check the source code of the original template files to get the list of the valid markups. Markups are self-explanatory.
10. Requirements, FAQ and Help
Requirements
FAQ/Troubleshooting
Makedoc relies on a core of a C/C++ parse engine. However, it does not cover all the syntax of this language, but only the most relevant subset for the documentation generation. Therefore, some writings like default variable values in constructor may not be recognised. Makedoc is designed to be fault-tolerant to such cases, and will simply issue a warning in the output window when the verbose mode is enabled.
At the moment, Makedoc does not include a real C pre-processor that can resolve #ifdefs. However, it is possible to remove #defined constants.
The function may simply not documented inside the source code as expected by Makedoc, i.e. there is no C comment given before the function implementation in the implementation file.
Another reason might be that the prototypes in header and implementation files do not exactly match. For example, on the one hand a namespace might be given explicitly for a given type whereas it might not be on the other.
This most probably happens because there is something defined between the keyword 'class' and the actual class name in the source code. A typical case for this is when a dll import/export command or any other macro is inserted for Windows. In that case, it is necessary to tell Makedoc to ignore these strings which are in the way. See the 'C define macros' entry in GFE makedoc.
Technical Information
11. About Documentation
12. Download and Installation
| Windows: | makedoc-Windows.zip |
| Linux Red Hat Entreprise 4 or equivalent: | makedoc-Linux-rhe4.zip |
Makedoc is packaged in a zip archive file. To install it, you just have to
extract the content on your disk in a directory of your choice. To uninstall it, remove simply the previously extracted files.
13. Change log
| 2006 May 3 |
Release v1.1:
|
| 2006 Jan 24 |
Release v1.0:
|
| 2006 Jan 19 |
Release v0.1:
|
The licensing philosophy of Makedoc is to relief any person interested in the tool from having to struggle with any licensing or administrative constraints. Therefore, there is no license key required nor any form to fill out for using Makedoc, it can be downloaded from this site and tried out immediately.
The Makedoc Graphical Front-End (GFE Makedoc) is licensed under the terms of the GNU license. Therefore, it can be copied, modified and distributed under the terms of this license.
The Makedoc Documentation Generator itself is licensed under specific terms which are detailed in the License Terms and Agreement for Makedoc. The following information aims at giving the most essential conditions for using Makedoc.
The payment of a license fee or a donation greater than 15$ gives right to the following services:
To purchase a license or make any donation, please email the following information to lloop@ersa-france.com :
Company name
Name
Forename
Postal Address
Country
Makedoc is FREE for use in the following cases:
| Condition | Price |
| Evaluation purposes, for 1 month from the first use. Once the evaluation period expired, all output documentation generated during evaluation must be removed if it does NOT fall under the conditions of the FREE use of Makedoc as described in this table. |
FREE |
| Private use and developments (eg. GNU projects) - home works | FREE |
| Independent workers, i.e. not directly employed by any business or organisation intended for lucrative purposes or not. | FREE |
| Students and any University or College staff | FREE |
The use of Makedoc is subject to a fee whenever it is used within any business, except if the generated output is not read and used over time by more than 2 people employed by or working for the business. This rule applies, but does not restrict to the following cases:
| Condition | Price | |
| It is used as part of the Quality Management System (QMS) of a business or any other organisation that has lucrative purposes. | 100 $ | |
| The outputs of the generator, i.e. generated HTML files, are read and consulted as documentation support by more than 2 employees or people working for a business or any other organisation in order to fulfill their business operation. | 100 $ per postal address | |
| The outputs of the generator, i.e. generated HTML files, are read and consulted as documentation support by more than 20 employees or people working for a business or any other organisation in order to fulfill their business operation (regardless of postal address). | 500 $ | |
| It is distributed as part of another product in the aim of making or not profit. | Contact ERSA at lloop@ersa-france.com | |
| Any use where Makedoc brings a valuable benefit in the business operation, e.g. when used as training tool in training courses. | Contact ERSA at lloop@ersa-france.com | |
| Any other situation for which it is not explicitly stipulated that Makedoc can be used free of charge. | Contact ERSA at lloop@ersa-france.com |
Roadmap for further developments:
This file is part of the Makedoc C, C++ and Qt Documentation Generator. Copyright (c) 2005-2006 Michel MEHL, France. All rights reserved. Makedoc is distributed by the company ERSA SaRL.
| Copyright (c) 2005-2006 Michel MEHL, Haguenau, France |
| Makedoc version 1.1 |