Re: [Pasdoc-main] [RFC] Parsing of the implementation section

[Michalis K. <mk...@po...>]

Mark de Wever wrote:
> On Thu, Dec 15, 2005 at 09:05:28AM +0100, Michalis Kamburelis wrote:
[...]
>>
>>As for visually separating things declared only in the implementation 
>>and those that are visible in the interface: I'm not sure is it really 
>>wanted. Simpler approach is to just take comments from the 
>>implementation section but *only for items declared in the interface*. I 
>>imagine that documentation generated by PasDoc is read by people who 
>>want to use documented unit. So they are not interested in seeing 
>>internal things that are declared only in the implementation section. In 
>>such case, you don't need any DefinedInImplementation property and you 
>>don't need to modify anything in html and latex outputs.
>>
>>argument for command-line option --parse-implementation:
>>  --parse-implementation=only-for-interface
>>or
>>  --parse-implementation=all
> 
> 
> I really want to have the _option_ to parse items not defined in the
> interface, this was the reason to start with working on it. 
> I want this because I want to be able to create two kinds of
> documentation:
> 1. The user documentation with information how to use a library
> ( only interface with public class members )
> 2. The developper documentation with information how to modify and extend
> a library ( interface and implementation and all class members )
> 

Indeed, this may be a good situation when it's appropriate to display
things visible only in the implementation.

> I was thinking about adding the member 'implementation' to the 
> --visible-members parameter. (Forgot to mention that in my original mail.)
> 

I would prefer to not overload --visible-members option for this. The
word "members" suggests that it should control only the members of
classes/interfaces/etc.

> If we want the option to scan the interface only for comment for items
> defined in the interface and the option to add also new items found in
> the implementation I like your parameters better.
> 

So, reading also Thomas's mail in this thread, I guess that yes, we want 
both options possible. So this is your way to go (if you want to please 
everyone, that is :) ).

When I was applying your patch in thread "Comments in program file" I 
realized that you will have to also parse uses clauses in implementation 
section. (this was even requested once, see 
[http://sourceforge.net/tracker/index.php?func=detail&aid=976519&group_id=4213&atid=354213] 
in the 4th question).

So then ParseUses call will be removed from ParseProgram and replaced 
with your ParseImplementationSection, and ParseImplementationSection 
will call ParseUses.

How are you going to display units used in the implementation section of 
the unit ? My proposition (that seems consistent to me right now) would 
be to
a) When --parse-implementation=only-for-interface, don't show them (they 
are internal details)
b) When --parse-implementation=all, show them, somehow marking that they 
are used in the implementation (e.g. you can just write string "(used by 
implementation)" after their names when displaying list of used units in 
html and latex outputs).

Michalis