Click here to Skip to main content
Click here to Skip to main content

Documenting Header Files

, 16 Sep 2003 CPOL
Rate this:
Please Sign up or sign in to vote.
This tool will turn a header file into an XML and/or HTML file for documentation purposes. The output may be merged with previously created or edited XML files.

Sample Image - HeaderDocumentorForm.gif

243 Files and 17 Days left

Once upon a time, there was a boss, who told his employees, that the customer wanted a fully documented source code. Though the source code was strewn with comments, some of them even useful, this was not what the customer thought of being documented. This customer thought of something like the documentation in the MFC or that alike. So, the boss told his employees to document each header file of the project. Each variable, each function, and each class. And he told them to have it finished at deadline day.

And this story is, why it ended as every fairy tale, and not as nightmare.

Setting up

We decided to split our efforts. One should seek for applications that could help us, one should sketch the layout of the documentation, and one should find out how to retrieve the information from a header file. After six hours, we met, and came to the conclusion that most likely we would fail. The main problem being the formatting of the resulting documentation files, which consumes about 3 to 4 hours per header file, resulting in roughly 800 hours or 100 working days for the whole process. That's when I created a new management rule:

  • If you want something stupid to be done, find someone stupid.
  • If you want it to be done fast, find someone more stupid.
  • If you want it be done repeatedly, find an idiot.

So, I looked around and I could not find an appropriate person. I looked into the mirror, probably close to, but still not quite fitting. I looked under my desk, and there it was: my computer. Two days later then, there was a program running, that read a header file and turned it into a formatted HTML file with all the information needed to make a documentation. The next ten days were just a Find And Replace of those ubiquitous "Here should be a description" by something more sensible. Binding those files to an HTML help project was just a delightful dessert.

No Files and 2 Days left

The boss and the customer were highly pleased, and the three programmers lived happily ever after, still waiting for the boss to pay them a beer.

Aftermath

Well, the boss could not only pay us a beer, and when I went jobless, I decided to turn this application into a more useful documentation system. The documentation layout was cast into a document template definition, and the output could be merged with an existing XML file. And this is the result.

The Program

This program is for documenting header files of C++ sources. If you feed it with other texts, like e-mails or real literature, you will find out that it will document nothing. Wink | ;) Thanks to Ben Bryant's CMarkup class, you do not need any XML engine running on your system. So, run the program, find a header file, tell the program where to place the documentation files, and be disappointed. This program only does formatting. The documentation has to be written by you. Remember the management rule? Smile | :) Then run any text editor, load the XML file created, and replace those "Here should be a..." with the information you want to share. Run this program again, load the same header file, and tell the program to read the modified XML file. Save and watch the result.

Behind the Mouse Clicks

On start up, the program tries to read an INI file, which tells it what to ignore (macros) and what words are not return values (like virtual).

When you locate a header file, this file is parsed. In detail, this means, all comments are stripped, and strings or source lines spanning more than one line are merged to one single line. All macros defined in the INI files are removed. All lines starting with the preprocessor sign (#) are eliminated, only the information from the #include lines are stored. All continuous white spaces are reduced to one space character. After that, the resulting text is 'beautified', that is, brought into a form for easier parsing. Then the result is scanned, and the information for variables, functions, and classes is stored away into some structures. The path and name of the header file is used to create reasonable names for the output files (HTML and XML).

When you tell the program to read an XML file, the information of this file is adjusted with the information stored. That way, any fitting description part of the XML file finds its way into the appropriate description part of the variable or function or class. Only the description part is used for merging, all the other stuff is only needed to address the correct fragment of the header file. The only exception is the CPP include list, which is taken from the XML file too. Those information are only retrieved, if no information was already stored. That way, you can use more than one XML file to retrieve the information. Then you may choose how the resulting HTML file shall be created. If you do not plan to use the HTML Help workshop or alike, please do not check the Create Splitfile box neither the Create automated Keyword box. The resulting XML file will always store all informations, regardless of the radio buttons. Those buttons and checkboxes are only used for HTML output. This program resembles more to a XSL(T) file. It reads an ill formed file (header file), transforms it into a well formed XML file, and then turns this XML file into an HTML file.

The Source Code

This program was planned to be a dialog based application, but I used the single document type for one and only one reason:

  • Print Preview.

Recognizing that a lot of text would be produced, I looked for some means not to save files, but to read the results just in time. Because most errors occurring can be perceived easily when reading the output, I used the print preview feature to display various stages of the process on screen. I left this feature so you can have a look at the source code if you are in a similar need as I was. The textual part is almost exclusively enclosed in one file (TextStrings.cpp) for ease of localization. The productive part (CreateOutputxxx.cpp, and TextStringsxxx.cpp) is also separated for each type, so it is easier to adopt it for different document types (E.g., RTF). The parsing of the INI file and of the header file might be interesting read, but is just plain programming technique.

Caveats

The provided source code will not compile. The files CMarkup.cpp/h are missing. Mr. Bryant does not want (t)his class to be uploadable from different places. I understand and accept fully his reasoning. So if you want/need to modify this source code, please have a look at FirstObject first. It is understood, that before downloading the files, you must read and agree to the licensing regulations. You need CMarkup V6.5 Evaluation release.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

G. Steudtel
Software Developer (Senior)
Germany Germany
No Biography provided

Comments and Discussions

 
GeneralSuggestion PinmemberEric Kenslow17-Sep-03 9:47 
GeneralRe: Suggestion PinmemberG. Steudtel17-Sep-03 9:58 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web02 | 2.8.141223.1 | Last Updated 17 Sep 2003
Article Copyright 2003 by G. Steudtel
Everything else Copyright © CodeProject, 1999-2014
Layout: fixed | fluid