extra line before PRO definition

[mgalloy]

If there is an extra line between the IDLDoc information and the procedure definition for the first (just first?) function in a file, the IDLDoc information is assumed to be at the file level rather than function level. This type of markup worked in IDLDoc2.0, so it is assumed to be in error.

Example of code that would cause a problem:

;+
; IDLDoc comments
; @param variable (in} a variable
;-

PRO name, variable

variable = 2

end

This would give an error like:

IDLDOC: routine level tag 'param' at file level in blah.pro

[mgalloy]

Author: jhood This holds true for other function definitions as well. I tested removing the blank line and the file level errors go away. This account for approx 940 'new' errors in my codebase.

[mgalloy]

Blank lines between the comment block and a routine are the indicator that the comment is not associated with the routine. Since IDLdoc 2.0 didn't have separate file comments (you had to use @file_comments), it didn't have to worry about this. I realize this breaks backward compatibility with IDLdoc 2.0, but it seems worth it to have a simple method of associating a comment block with a file or routine. It also has a relatively simple fix of deleting the blank line (though 940 blanks lines would surely be a pain).

To mitigate this issue, I have tried to add all possible routine level tags to the file level as well. Only tags that don't make any sense at the file level are excluded (i.e @params, @keywords, @returns). And, as the error message indicates, I added a warning when using a routine level at the file level.

In any case, I should probably construct a list of backward compatibility issues and add this one.

[mgalloy]

Author: jhood Thanks for the comments. I thought that might be the hard truth. I am working on a sed script that may help solve the problem quickly. I will also post other sed that I am using to solve compatibility issues.

More thorough compatibility documentation would be great when you can make the time.

Having the errors there isn't all bad as at least it lets me know when the documentation wouldn't read correctly.

[mgalloy]

Separated the ISSUES files into "Known bugs" and "Backward-compatibility issues" sections and added this issue to it.