ok, so I just made a copy of the IDL template (template.pro from the examples directory of the IDL installation) into my own source directory, without changing anything.
I generated documentation from it with idldoc 3.3 (from the idl 8.0.0 workbench, and Windows 7).
I still get a very poor documentation from the generated template.html file.
I get content from only 6 sections (PURPOSE, SIDE EFFECTS, RESTRICTIONS, PROCEDURE, EXAMPLE, and MODIFICATION HISTORY) and thats all, and even these sections name do not show in the documentation, its only their content, so you do not know where this comment comes from
MODIFICATION HISTORY is displayed as Author information which is not really right.
As for the routine parameters and keywords, only their name is given, not the associated comment (I also tested idldoc with a lot of correctly idl format documented routines with a lot of commented parameters, and I got no comment at all for any of the parameters/keywords, which is a real pity)
So, should we not use the idl format and only use the rst and idldoc formats to get a correct result ? Or is there a way to improve the idl format result?
I could use the rst format, but most of the idl libraries I use (found on the web, like coyote or catalyst...) are documented using the idl format...
Reported by steven in the [http://michaelgalloy.com/2010/10/20/idldoc-3-3-released.html/comment-page-1#comment-265757 comments for the michaelgalloy.com post on the IDLdoc 3.3 release]:
ok, so I just made a copy of the IDL template (template.pro from the examples directory of the IDL installation) into my own source directory, without changing anything.
I generated documentation from it with idldoc 3.3 (from the idl 8.0.0 workbench, and Windows 7).
I ran this command on the workbench console:
I still get a very poor documentation from the generated template.html file.
I get content from only 6 sections (PURPOSE, SIDE EFFECTS, RESTRICTIONS, PROCEDURE, EXAMPLE, and MODIFICATION HISTORY) and thats all, and even these sections name do not show in the documentation, its only their content, so you do not know where this comment comes from
MODIFICATION HISTORY is displayed as Author information which is not really right.
As for the routine parameters and keywords, only their name is given, not the associated comment (I also tested idldoc with a lot of correctly idl format documented routines with a lot of commented parameters, and I got no comment at all for any of the parameters/keywords, which is a real pity)
So, should we not use the idl format and only use the rst and idldoc formats to get a correct result ? Or is there a way to improve the idl format result?
I could use the rst format, but most of the idl libraries I use (found on the web, like coyote or catalyst...) are documented using the idl format...