search

mgalloy / idldoc

Documenting IDL code
Other
21 stars 13 forks source link

"warnings generated" output doesn't match idldoc-warnings.html #37

Closed mgalloy closed 11 years ago

mgalloy commented 11 years ago

It's not clear how idldoc "warnings" are defined. I can execute idldoc on a set of routines and the IDL output log window will say "0 warnings generated". However, in the idldoc-warnings.html file that's created, I may have a number of files listed with partial or no documentation. I use the latter file quite a bit to make sure my comments are consistent with my code. Maybe there needs ot be a separate category name for items that are warnings of a different type. It'd also be nice if there was more detail when documentation is only partial, for example, "missing keyword description" or "missing return value description". Those are the two most common I run across.

mgalloy commented 11 years ago

This is an error in labeling: the "warnings" that IDL print in the output log are basically syntax errors in your documentation syntax, the "warnings" on the idldoc-warnings.html page are incomplete documentation. Maybe the idldoc-warnings.html page could be labeled "Incomplete documentation warnings"?

Yes, I've thought about adding more detail to the partial documentation listing. It will just be a bit of a pain.

mgalloy commented 11 years ago

Well, on second thought, how about adding another category on the idldoc-warnings.html page that is "Syntax errors"?

mgalloy commented 11 years ago

This is ticket #8 already. The suggestion there is to make a "Runtime warnings" section, but the same idea.