doxygen | Thomas' Work Space

How to define your own conditional content marker “Internal” for Doxygen

2015/05/06 plagwitz Leave a comment

Doxygen comes with a built-in conditional content marker \internal the outputting of which can be controlled with the switch INTERNAL_DOCS in Doxygen’s config file.
However, I could not get this to work as advertised in Doxygen 1.8.8.
In cases of similar feature breakage, users are commonly advised to fix the error in the Doxygen source. If you, like I did, lack the time for that, here is a simple workaround which uses another built-in feature that an be controlled via Doxygen’s config file:

Define as one of the:

ALIASES = "myinternal=\if myinternal <HR><kbd><em>" \
          "endmyinternal= </em></kbd> \endif"
# HTML is optional, intended to make internal information stand out clearly if outputted

Switch this ALIAS on and off using ENABLED_SECTIONS = # myinternal

Example usage in a .dox file:

-# A high-low-high-low beep sequence followed by a low-high beep
 sequence indicates successful pairing and connection to the remote
 device.
 @myinternal tested with barcode on lower-end of cradle: gives success
 beep sequence @endmyinternal
 -# A long low, long high beep sequence indicates unsuccessful pairing.

Categories: e-infrastructure, service-is-documenting, service-is-testing-troubleshooting-debugging Tags: doxygen

Doxygen config reformatted for Excel

2015/04/16 plagwitz Leave a comment

Apart from the almost 150 markup tags Doxygen 1.1. supports (not to mention HTML tags that are supported also),
the Doxygen config file in version 1.8.8 has over 260 settings, many with complex interrelations.
To facilitate working with so many options, especially when testing. I reformatted the default config file for import into Excel,
where I can more easily sort, search and filter,
and export columns L-R whenever I need to update the doxygen.config file:

Below is a live, downloadable view:

Categories: e-infrastructure, Spreadsheets Tags: doxygen, MS-Excel

Getting Eclipse CDT to spell check non-source files

2015/03/02 plagwitz Leave a comment

Problem:
1. Using Eclipse Luna CDT, with C/C++ spelling engine, to document C and C++ code in Doxygen (Eclox plugin),
2. Spell check works for inline Doxygen documentation. My API-level code comments in *.[ch](pp)* files gets spell-checked alright (Well…:
  1. I had to download a decent dictionary to avoid recommendation like this one: . I am using the aspell dictionaries from here and here. This is before a restart/recheck:
  2. I still do not know how to teach the C++ spell check engine that a newline does not start a new sentence:
  3. The oft-referred to menu: Edit / Spell check does not show up for me:
3. However, spell check ignores my standalone *.dox files with high-level documentation.
What I have tried:
1. Telling Eclipse about the*.dox file type:
2. Associating *.dox files with the Doxyfile editor: . Fail. This tool from the Eclox plugin seems to help only with the editing of the Doxygen config file.
3. Associating *.dox files with C/C++-editor: Fail: has no effect.
Workaround:
1. Terrible, but since a similar question is still open on stackoverflow): If you can (*.dox requires all comments to be within c-style comments anyway), rename your *.dox files to *.dox.cpp. Terrible, but works:
2. A bit less terrible if you mange to store your standalone *.dox files as *.dox.cpp permanently do this if you get your Doxygen to handle these extensions.
3. What is nice to see is that the spell-checker recognizes Doxygen’s built-in reserved words (as opposed to my custom-defined Doxygen-commands).
Other things to try:
1. I could not get Hunspell4Eclipse to work, despite going to considerable trouble getting the marketplace into my Eclipse installation
2. I have not tried eSpell.

Categories: e-infrastructure, service-is-configuring-learning-tools, service-is-documenting Tags: c#, cdt, doxygen, eclipse, eclox, espell, hunspell4eclipse, proofing-tools

Bringing method documentation back into synch by using Textpad command line to jump to GrepWin matched line in file

2015/02/14 plagwitz Leave a comment

Objective: is checking, in one simple result window, multi-line matches of method signatures and their Doxygen comments from a multi-module, multi-directory C++ codebase, in order to spot inconsistencies, i.e. where code and documentation are out f synch:
All this short of having to write a Parser or buying a tool like Atomineer Pro Documentation (which does look like it is “right on the money”, but, as it turned out to my surprise, also far short of getting this to work in Eclipse or on a Bash command line with Grep and Perl, ack (doesn’t do multi-line matches!), ag, or what-not. grepWin is free, has an easy-to-use, versatile interface, and proves, once again, to be a powerful little tool.
A a sample (in reality not cut off, of course), 2 methods with their comments showing here:
And I am only a click away from correcting errors I spot in my preferred editor that grepWin can link in “Settings””C:\Program Files (x86)\TextPad 7\TextPad.exe” %path%(%line%,0)
Some grepWin quirk I do not understand:
1. Why does the “Search” button do nothing when I select radio button “Regex” instead of “Text Search”, but does the expected regex match against file and directory name when I select the latter?