[idldoc] parser trouble

[Michael Galloy]

On Dec 4, 2007, at 4:06 AM, Françoise Pinsard wrote:
> I notice that if we have some ";" between ";-" and "function", IDLDOC
> parser doesn't handle tags properly.
>
> for exemple with the source my_routine.pro I can see this warning :
>  Parsing my_routine.pro...
> % IDLDOC: unknown tag "returns" in file my_routine.pro
>
> when I remove the ";" on line 17, no more warning !!
>
> Can you please tell me we have to remove all our extra ";" or if you  
> can
> fix this problem in a next release ?

Ah, yes this is the "desired behavoir". There is a difference between  
IDLdoc 2.0 and 3.0 -- in IDLdoc 3.0 any comment block (i.e. enclosed  
between ;+ and ;-) that is *immediately* before or after a routine  
header is a "routine comment". If it's not immediately before or  
after, then it's a file comment. There are different tags (though some  
are shared) for the different blocks.

So for example,

;+
; File level comments. They will appear at the top of the documentation,
; before any of the routines' documentation.
;
; @author this is claiming authorship of the entire file.
; @returns this would be an warning and this tag would be ignored
;-

;+
; This is a routine level comment.
;
; @author this is claiming authorship of just this routine
; @returns this is OK
;-
function test
   return, 1
end

;+
; This is actually a file level comment because the ;- is not  
*immediately* before the "function".
;-
;
function my_routine
   return, 1
end

I suppose the specification for file level comments could be changed  
to require a blank line, so that a comment block could be "attached"  
to a routine with plain ;'s. Any thoughts?

Mike
--
www.michaelgalloy.com