Archive

Posts Tagged ‘doxygen’

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

  1. 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.
  2. However, I could not get this to work as advertised in Doxygen 1.8.8.
  3. 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:
  4. 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
  5. Switch this ALIAS on and off using ENABLED_SECTIONS       = # myinternal
  6. 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.

     

Doxygen config reformatted for Excel

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

Below is a live, downloadable view:

Getting Eclipse CDT to spell check non-source files

  1. Problem:
    1. Using Eclipse Luna CDT, with C/C++ spelling engine, to document C and C++ code in Doxygen (Eclox plugin), image
    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: image. I am using the aspell dictionaries from here and here.  This is before a restart/recheck:image
      2. I still do not know how to teach the C++ spell check engine that a newline does not start a new sentence: image
      3. The oft-referred to menu: Edit / Spell check does not show up for me: image
    3. However, spell check ignores my standalone *.dox files with high-level documentation.
  2. What I have tried:
    1. Telling Eclipse about the*.dox file type: image
    2. Associating *.dox files with the Doxyfile editor: image. Fail. This tool from the Eclox plugin seems to help only with the editing of the Doxygen config file. image
    3. Associating *.dox files with C/C++-editor: image Fail: has no effect.
  3. 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: image
    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). image
  4. 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.

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

  1. 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: image
  2. image
  3. 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.
  4. A a sample (in reality not cut off, of course), 2 methods with their comments showing here: image
  5. 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)
  6. image
  7. 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? image