Upgrading to IDLdoc 3.0

IDLdoc 3.0 is not completely compatible with IDLdoc 2.0. This page lists the issues and provides some help for cleaning up code to produce fewer warnings when running the new version.

Backward-compatibility issues

• A comment block separated from a routine header by a blank line would be associated with the routine in IDLdoc 2.0, but is considered a file level comment in IDL 3.0. In particularly, param, keyword, and returns tags in that comment block would now generate warnings since they are routine level comment tags in a file level comment.
• The "inherits" tag was obsoleted. Inherited classes are automatically found by IDLdoc.
• The ASSISTANT and PREFORMAT keywords to IDLDOC were obsoleted. The IDL Assistant is not likely to be supported much longer by IDL, so the assistant format was not reimplemented for IDLdoc 3.0. With the introduction of the IDL format and the ability to add further formats, the PREFORMAT was deemed unnecessary to reimplement.

Scripts to cleanup code

Here is a list of sed scripts that Joe Hood used to tidy up his code for IDLdoc 3.0.

As noted in ticket #25 some of these won't be bulletproof, but they may help. Joe says:

I suggest doing a diff between new and old to confirm that it worked on your code base, if you decide to use them. I got rid of about 750 warnings with them, so I hope they can be of help.

The first script, finds @file_comments and replaces that text with nothing. Note this isn't a problem anymore, but you still may wish to remove them as they aren't needed at the file level. This will be dangerous if you have @file_comments at the routine level!

 find . -type f -name '*.pro' -exec sed -i 's/@file_comments//g' {} \;

The following line finds lines with @inherits and deletes them. As noted in ticket #25 it only works if all related info is on the same line:

find . -type f -name '*.pro' -exec sed -i '/@inherits/ D' {} \;

The next set is to remove whitespace between ;- and pro of function definitions. This could also pull file comments up close in some cases so be sure this will work for you.

The following removes all trailing whitespace to ensure next matching will work:

find . -type f -name '*.pro' -exec sed -i 's/[ \t]*$//' {} \;

The following script finds blank lines between ;- and pro/PRO IDL definition and remove them. Notes: i makes it case insensitive.

find . -type f -name '*.pro' -exec sed -i '
 /;-/ {
        N
        N
        {
        s/;-\n\npro/;-\npro/i
        }
}' {} \;

Note: this needs to be multiline. With N it seems you need a newline after it to work, though someone may know other ways to do this. You can do something similar for functions, and add in extra 'N' and '\n' to catch two blank lines, etc.