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

[Mark de W. <ko...@xs...>]

On Thu, Dec 15, 2005 at 09:05:28AM +0100, Michalis Kamburelis wrote:
> Mark de Wever wrote:
> >I just started to implant the parsing of the implementation section of
> >an unit and it seems to work pretty well.
> >
> >Classes in the implementations are not parsed and generate an error.
> >Definitions and procedures inside a procedure are ignored.
> >If people really want this, then let me know.
> >
> >The following questions have occurred:
> >
> >1. What should we do with comment for a (class) method which already has
> >comment, ignore or add another paragraph in the document if so before or
> >after the comment in an external document? I'd perfer to drop the
> >comment.
> >
> >2. For forward declared procedures in the implementation I prefer to get
> >the comment from the forward declaration. If nothing declared then 
> >look at the real procedure for comment. In both cases also use the 
> >external documentation. For procedures only implanted without a forward
> >declaration the comment at the implementation is used.
> >
> >3. I think it would be wise to show in the output somehow what is defined
> >in the implementation and what not. For the HTML output I would suggest
> >another header row in the output with the same links but to the
> >implementation section. When using the sidebar not showing these items.
> >
> >4. I'm not familair with the Latex output so I've no suggestions for that
> >part.
> >
> >5. To separate between items defined in the interface and the 
> >implementation, I would suggest we add a boolean DefinedInImplementation 
> >in TBaseItem.
> >
> >6. If somebody has other ideas, please let me know.
> >
> 
> First of all, parsing implementation section must be activated by some 
> command-line option, like --parse-implementation. Without this option 
> pasdoc behaves like it did, and doesn't take any comments from the 
> implementation section.
> 
> Now, before I say anything else, I want to admit that I will *not* be 
> the user of this feature (I still prefer to keep my non-internal 
> comments only in the interface), so I'm just "throwing some ideas" here. 
> I depend on other people (that will actually use this feature) to 
> comment more. Anyone who contributed to the page 
> [http://pasdoc.sipsolutions.net/WantedFeaturesParsingImplementation]: 
> speak up now to clarify how you want this feature to work.
> 
> Now, some ideas that you may consider:
> 
> 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 )

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

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.

> If you're sure that you want to show in the documentation things that 
> are not visible in the interface, then I think you should show them by 
> some small rectangle on the left side of the declaration, exactly like 
> the "visibility cell" of the classes' members (public, protected, 
> private etc.) is shown. All you will have to do is to
> 
> a) prepare another image img/defined_in_implementation.gif (based on 
> e.g. img/private.gif in pasdoc sources)

I like that idea. 

> b) modify TGenericHTMLDocGenerator.WriteVisibilityCell to take 
> additional "ShowDefinedInImplementation: boolean" param and if 
> ShowDefinedInImplementation is true then it looks at 
> "Item.DefinedInImplementation" and if "Item.DefinedInImplementation" is 
> true then it displays img/defined_in_implementation.gif there. When 
> Item.DefinedInImplementation is false it leaves the visibility cell 
> empty. LaTeX output may be modified analogously, I can handle this for you.
> 
> Last note: add DefinedInImplementation property to TPasItem class, not 
> to TBaseItem class. Everything declared within a unit is TPasItem.

Oke I will do that.

> That's it. Once again, I want to say that I will not use this feature, 
> but I'm very happy that Mark is willing to contribute this, because it 
> was requested many times. I depend on other people to clarify how they 
> prefer this feature to exactly work.
> 
> Michalis

Mark de Wever