[idldoc] parser trouble

[Françoise Pinsard]

> 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?

ok I understand better the two levels. Even if I usualy recommand to have
one routine in one source file, it is not alway possible.

I don't think you have to add the requierement of a blank line.

May be just modify the warning message :
Instead of
 IDLDOC: unknown tag "returns" in file tp1.pro
Can you write something like
 IDLDOC: unknown tag "returns" in file tp1.pro (line xx) at file level
comments

-- 

Françoise Pinsard
LOCEAN - IPSL
UMR 7159 CNRS/IRD/UPMC/MNHN
Université Pierre et Marie Curie aile 45-55 5 étage pièce 516
Case 100 - 4 Place Jussieu  75252 Paris cedex 05
Tél. +33 1 44 27 47 65  Fax +33 1 44 27 71 59
mailto:Francoise.Pinsard at locean-ipsl.upmc.fr
http://www.locean-ipsl.upmc.fr/