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

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

On Fri, Dec 16, 2005 at 02:53:11PM +0100, Michalis Kamburelis wrote:
> Mark de Wever wrote:
> >On Thu, Dec 15, 2005 at 11:17:48PM +0100, Michalis Kamburelis wrote:
> [...]
> >>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).
> >
> >
> >I don't get the question, how or when? I assume when.
> >We can do that, was thinking of maybe a third one
> >
> >--parse-implementation=only-uses
> >
> >To only get the uses clause, so pasdoc can find the other units it needs
> >to parse.
> >
> 
> My question was both "how and when". The final decision in this regard
> is up to you, but I think that the third version like
> --parse-implementation=only-uses is not needed. Looking at your sample
> output, in the "uses" clause of test_unit you show a list:
> 
>   * a_unit
>   * another_unit
> 
> My proposition was to show only
> 
>   * a_unit
> 
> when --parse-implementation=only-for-interface was used (or no
> --parse-implementation=xxx was used at all). And to show
> 
>   * a_unit
>   * another_unit (used by implementation)
> 
> when --parse-implementation=all was used. So you show in this case that
> "another_unit" is used, and at the same time you're clearly showing that
> it's used only by implementation.
> 
> Of course, this is all assuming that --write-uses-list option was also
> specified, without --write-uses-list no "uses" section is shown at all.
> 
> So I don't think that --parse-implementation=only-uses is needed. I see
> it like this: --parse-implementation=all shows all internal details
> about implementation (all items (procedures etc.) defined in the
> implementation, and all units used in the implementation) and
> --parse-implementation=only-for-interface doesn't show these internal
> things (so it doesn't show items that are visible only in the
> implementation and it doesn't show units that are used only by the
> implementation).
> 
> [...]
> >In reply to myself maybe a switch to --write-uses-list would be a better
> >option.
> 
> Introducing an argument for --write-uses-list option would break
> compatibility (because then everyone would have to always pass some
> argument to it). I don't think it's necessary, see above.
> 
> Michalis
>

Oke I'm going to use the two command line switches

--parse-implementation=only-for-interface
and
--parse-implementation=all

When an item defined in the interface has a comment in both the 
interface and the implementation, what would people prefer to do. 
I think we should give a warning and use the comment in the 
implementation, just like the backcomment now does to a normal 
comment in the interface. When also defining a backcomment in the
implementation ( I don't know why one would do so ) that one would
override the previous one. Thus simply always use the method, last
comment sticks.

If nobody objects, I'm going to make it like this. 

Regards,
Mark de Wever