10 Responses to “IDLdoc 3.3 released”

1. steven says:
   November 16th, 2010 at 11:34 am

   Hi,

   I’m using idldoc from the idl8 workbench (on Windows7).
   It works well with “rst” comments, but I get nearly nothing with “idl” comments.

   I run this command on the workbench console:

   idldoc, root='path_to_my_src_dir', output='path_to_my_doc_dir', $
           format_style='idl'

   I get nearly nothing in the idldoc generated toto.html page
   For instance, I have no “author” mention, no “calling sequence”…

   Here is my very simple prog :

   ;+
   ; NAME:
   ;    toto
   ;
   ; AUTHOR:
   ;    Etienne
   ;
   ; PURPOSE:
   ;    The goal of this is to be a very short program
   ;    As you can see
   ;
   ; CATEGORY:
   ;    none
   ;
   ; CALLING SEQUENCE:
   ;    just call it by its name
   ;
   ; INPUTS:
   ;    a
   ;    b
   ;    c
   ;-
   pro toto, a,b,c,key1=key1,key2=key2
     print, "hello"
     print, "again"
     a = b+5
   end

2. Michael Galloy says:
   November 16th, 2010 at 3:02 pm

   There is no author tag in the IDL template (see the file template.pro in the examples directory of the IDL installation). The calling sequence tag is ignored and derived from the actual code.

3. steven says:
   November 19th, 2010 at 10:53 am

   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:

   idldoc, root=’path_to_my_src_dir’, output=’path_to_my_doc_dir’, $ format_style=’idl’

   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 that’s all, and even these sections name do not show in the documentation, it’s 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…

4. Michael Galloy says:
   November 19th, 2010 at 11:35 am

   I will look into the IDL format a bit more. (I’m going to make the above comment into a ticket for IDLdoc 3.4.)

   But, in the long run, it will not get the attention that the rst format will get. I suggest using rst for any new code and to slowly migrate code that you control over to rst. I am not going to get rid of the IDL format, though.

5. Michael Galloy says:
   November 19th, 2010 at 11:41 am

   It’s ticket #70 on the Trac site if you want to follow it.

6. steven says:
   November 22nd, 2010 at 3:28 am

   ok, then what about the “idldoc” format ?

   It looks to me that this is a quite a more standard format (close to the one used in javadoc, and doxygen…) than “rst”.

   I know very little about rst, apart that it would come from the Python world. Is there any chance that it will be used in other languages than IDL, for instance in Java ? in Php ?

   As for me, I’d rather use “idldoc” than “rst” as it looks more “compliant” with javadoc and doxygen…

   It’s just a pity that “idldoc” is not integrated in the Idl 8 Workbench (“rst” is).

7. Michael Galloy says:
   November 22nd, 2010 at 5:29 pm

   Yes, the idldoc format is more “standard”, i.e., its syntax looks similar to Javadoc’s and Doxygen’s. But the same tools don’t run on IDL code, so the “standard” doesn’t really get you anything (maybe it is a bit easier to learn if you are already familiar with Javadoc or Doxygen).

   In the end, I think the rst format is way easier on the human eye and worth being non-standard (it’s not even fully compliant with the restructuredText syntax used in Python).

8. Michael Galloy says:
   November 22nd, 2010 at 5:31 pm

   IDLdoc was the first format syntax, so it’s support should be nearly identical to rst’s. Also, you can use IDLdoc as your format and rst as your markup, i.e., FORMAT_STYLE=’IDLdoc’, MARKUP_STYLE=’rst’, then you should have all the features available with the rst format style.

9. steven says:
   November 23rd, 2010 at 11:13 am

   I saw that the new idl routines in idl 8 (like lib/graphics/graphic.pro or plot.pro…) are documented in “rst”, which is a good argument for using this format from now on.

   So, I tried to document all the lib/graphics/ directory with idldoc using this command :

   idldoc, root=’C:/Program Files/ITT/IDL/IDL80/lib/graphics/’, output=’my_doc_output_path’, format_style=’rst’

   But I was a bit disappointed, because I don’t get all the comments as expected. For instance, the parameters (:Params:) don’t show their associated comments…

   I guess this is because these comments should be something like “in, required, type=string” and not a free comment (which should be placed on a line underneath)…

   Anyway, is there a way this could be improved ? Otherwise, we should train the ITT people on how to use the “rst” format properly…

10. Michael Galloy says:
    November 23rd, 2010 at 12:59 pm

    Ah, thanks for pointing that out, I didn’t know the new graphics stuff was using the rst format (sort of). Maybe I should do a workshop or something at ITT VIS…