New subject: More on documentation tool

2 Mar 2003

      On Fri, 2003-02-28 at 15:09, Frank Heckenbach wrote:
<big snip>
...
...

When moving the vars into the section in which they are declared

should I make a menu entry for each one or should I do a submenu of
vars?
Good question. I'd say it depends. Sometimes, each one deserves its
own entry, other times, there are a list of them which belong
together (e.g., the color constants in the CRT unit).
Of course, the program can't find this out automatically. One rule
might be, if there's a comment for each of them, put them in
separate sections, like here:
var
  { Address of the lowest byte of heap used }
  HeapLow: PtrCard; asmname '_p_HeapLow'; external;
{ Address of the highest byte of heap used }
  HeapHigh: PtrCard; asmname '_p_HeapHigh'; external;
{ If set to true, `Dispose' etc. will raise a runtime error if
    given an invalid pointer. }
  HeapChecking: Boolean; asmname '_p_HeapChecking'; external;
Yes the above is going to strait forward to implement.
...
But if there's only one comment at the top, put them in one section
all together:
const
  { Foreground and background color constants }
  Black         = 0;
  Blue          = 1;
  Green         = 2;
  Cyan          = 3;
  Red           = 4;
  Magenta       = 5;
  Brown         = 6;
  LightGray     = 7;
Of course, in the indices, there should be entries for each of them.
Now this is tricky: 
1) What do you call the node/section for this list of vars/functions
ect...?
2) You can't just assume that because there is not a comment that it
belongs to what was above. If you do what happens for those cases where 
I haven't finshed writing the documentation for my code?
I'm thinking that to solve this we are going to need a group command. 
Something like {@group group name} .... {@end group } 
Where 'group name' would be the name used for the section/node.
And Yes I agree that every item needs to be placed in the index but what
happens in the case where you don't want them all in the index. maybe a
option to the @group command.
...
...

If I where to put them in the section menu how about this menu sytle:

@menu

MaxInt::	Const
SomeVar::	Var
SomeType:: 	Type
FuncFoo::	function
ProcFoo::	Procedure

@end menu
Or 
@menu

Const MaxInt::
Var foo::
Type foo::
SomeFunc::
SomeProc::

@end menu
Since the left part of the menu corresponds to the node name, I
prefer the former, so the node name equals the identifier.
BTW, you sent this mail personally, so I'm replying personally. If
it was meant for the list, feel free to forward and/or quote my mail
there.
Sorry about that.. This one is going to the group...
...
Frank
Oh FYI I've started to work on a manual for pas2texi. As soon as I get it roughed
in I will send a copy to the list.
Richard

Re: More on documentation tool