mgalloy
commented
11 years ago IDLdoc is not actually deleting whitespace, the verbatim markup just copies directly to the output file -- in HTML, this will look smashed together. Try using MARKUP_STYLE='rst' on the IDLDOC call (or use docformat = 'IDL rst' in individual source files). I think this should meet requirement 1. Let me know if this is so.
I have thought about adding user-defined sections as in requirement 2 before. That won't make the next release, but I'll keep it in mind.
I use IDL style documentation in my code and, for the most part, am delighted with the organization that IDLdoc brings to that documentation. However, two aspects of my commenting are consistently handled poorly by IDLdoc:
1) Deliberate use of whitespace (for example, adding a newline between each revision under the MODIFICATION HISTORY header, or including lists / indented code snippets in the PURPOSE header). IDLdoc deletes the whitespace when parsing, and lumps this text together in a rather ugly looking paragraph.
2) I sometimes include my own headers, in addition to the ones recognized by IDLdoc (like PURPOSE or INPUTS, etc). IDLdoc lumps these blocks of text into the PURPOSE header, ignoring newlines, etc.
Personally, I would really appreciate it if IDLdoc preserved newlines when parsing comments. In addition, if it finds a header that it doesn't recognize (i.e. any capatalized text ending in a colon and separated by the initial semicolon by one space), it should create a section for it in the IDLdoc output, and copy its contents verbatim (preserving whitespace). This would greatly enhance IDLdocs flexibility when using IDL style comments.