pasdoc-main

[Pasdoc-main] Parsing of the implementation section

[Markus J. <jo...@in...>]

Hi, I came across this thread in the mail archive:
http://sourceforge.net/mailarchive/message.php?msg_id=6103275
Apparently Mark de Wever worked on this feature. Unfortunately I 
couldn't find any trace of his work in any svn revision. So could 
anybody tell me what happend to it, and if his changes are available 
somehow, so that I could give them another try?

TIA

Markus

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

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

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.


Regards,

Mark de Wever

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

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

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.

It's also possible to implement both behaviors, by e.g. requiring 
argument for command-line option --parse-implementation:
   --parse-implementation=only-for-interface
or
   --parse-implementation=all

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)

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.

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

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

[Thomas M. <dum...@gm...>]

Hi Michalis,

On 12/15/05, Michalis Kamburelis <mk...@po...> wrote:

> > I just started to implant the parsing of the implementation section
> > of an unit and it seems to work pretty well.

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

I agree.

> 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),

A collegue of mine has recently complained that all those comments in
the class declaration make the code unreadable and that those comments
should really go into the implementation section where they don't
interfere with the code so much. I think he has got a point there.

> 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*.

Yes, that's a good idea. I think that most people who want to use the
implementation section comments won't put any comments into the
interface section anyway. (at least not for methods and plain
procedures/functions, there will still be comments for classes,
constants, variables - where else could you put them?)

twm

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

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

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

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

On Thu, Dec 15, 2005 at 11:17:48PM +0100, Michalis Kamburelis wrote:
> Mark de Wever wrote:
> >On Thu, Dec 15, 2005 at 09:05:28AM +0100, Michalis Kamburelis wrote:
[...]
> 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.

I haven't looked in how it was implanted, but thought it would be easy
this way, but since we go for 2 ( or 3 see below ) options this wouldn't
make sense anymore.

> 
> >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 :) ).

I probably should make a funny comment now... ;)

> 
> 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).

See my latest response there.

> 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).

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.


> 
> Michalis

Attached a sample output of how it parses everything at the moment, the
implementation items are not marked. The archive shows the output
generated for test_unit.pp, also in the archive.

Mark

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

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

On Fri, Dec 16, 2005 at 10:15:25AM +0100, Mark de Wever wrote:
[..]
> 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.

In reply to myself maybe a switch to --write-uses-list would be a better
option.

Mark

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

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

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

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

[Johannes B. <joh...@si...>]

On Fri, 2005-12-16 at 14:53 +0100, Michalis Kamburelis wrote:

> So I don't think that --parse-implementation=3Donly-uses is needed. I see
> it like this: --parse-implementation=3Dall shows all internal details
> about implementation (all items (procedures etc.) defined in the
> implementation, and all units used in the implementation) and
> --parse-implementation=3Donly-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).

Hmm. I was going to write that this makes sense, but I'm kinda late in
the game :)

> [...]
> > In reply to myself maybe a switch to --write-uses-list would be a bette=
r
> > option.
>=20
> 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.

This, however, doesn't make sense ;) It should be perfectly possibly to
make a string option default to one value if it is given and another if
it is not given (though the current OptionParser might not allow it it
should be easy to add).

Anyway, I digress. I don't think adding it to --write-uses-list makes
sense either since then you have to use --parse-implementation together
with that to get full output. In fact, I think I'd prefer the following
possible settings along with a rename from --parse-implementation to
--show-implementation:

--show-implementation       given: default to all
                        not given: default to nothing
                  possible values: all,nothing,only-for-interface

--write-uses-list           given: default to yes
                        not given: default to no
                  possible values: yes,no,only-interface
                            [only-implementation doesn't make sense]

The reason for renaming from --parse-... to --show-... is that the
actual parsing is just a detail of what pasdoc needs to do to fulfil the
goal of showing the comments in the implementation section, and I think
the command line options should be named after the goal not the process.

What do you think?

johannes

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

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

Johannes Berg wrote:
> On Fri, 2005-12-16 at 14:53 +0100, Michalis Kamburelis wrote:
[...]
>>
>>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.
> 
> 
> This, however, doesn't make sense ;) It should be perfectly possibly to
> make a string option default to one value if it is given and another if
> it is not given (though the current OptionParser might not allow it it
> should be easy to add).
> 

Uhm, it's not possible. No command-line program does it, and pasdoc also 
can't. Here's why:

   pasdoc --language en foo.pas

is equivalent to

   pasdoc --language=en foo.pas

This looks natural, and is handled by pasdoc and pretty much every other 
command-line program. But if you will allow options to have an 
*optional* argument, then how you will handle the 1st case,
   pasdoc --language en foo.pas

Is the "--language" option without an argument (and thus should take 
some default argument value) and "en" is just another filename to parse 
for pasdoc, or is "en" an argument for preceding "--language" ? Of 
course in this case there is a finite number of allowed arguments for 
--language option, so we could just check whether the parameter 
following the "--language" looks like some language code or not. But 
this is obviously not a nice solution.

That's why if your option takes an argument -- then user *must* specify 
the argument, always. That's what pasdoc (and all other command-line 
programs ?) currently do, and I don't see how it can be changed...

> Anyway, I digress. I don't think adding it to --write-uses-list makes
> sense either since then you have to use --parse-implementation together
> with that to get full output. In fact, I think I'd prefer the following
> possible settings along with a rename from --parse-implementation to
> --show-implementation:
> 
> --show-implementation       given: default to all
>                         not given: default to nothing
>                   possible values: all,nothing,only-for-interface
> 
> --write-uses-list           given: default to yes
>                         not given: default to no
>                   possible values: yes,no,only-interface
>                             [only-implementation doesn't make sense]
> 
> The reason for renaming from --parse-... to --show-... is that the
> actual parsing is just a detail of what pasdoc needs to do to fulfil the
> goal of showing the comments in the implementation section, and I think
> the command line options should be named after the goal not the process.
> 

As for renaming --parse-implementation to --show-implementation: sure, 
you're right.

As for "default to all" and "default to yes" above : this is not 
possible, like I explained above, there's no sane way to parse such 
options... And this means that introducing argument for 
--write-uses-list will break compatibility.

My proposition was just to leave --write-uses-list as it is, and let 
--show-implementation decide whether "--write-uses-list means to show 
all uses" or "--write-uses-list means to show only interface uses".

Otherwise, if we really want to have a way to show implementation uses 
clause but not items declared in the implementation, we can make new 
option, like "--write-uses=yes/no/only-interface" and say that 
"--write-uses-list" is just a shortcut for "--write-uses=yes". That's 
the way how we can keep compatibility.

Michalis

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

[Johannes B. <joh...@si...>]

On Mon, 2005-12-19 at 14:27 +0100, Michalis Kamburelis wrote:

>    pasdoc --language en foo.pas

Right. Didn't think of that.

> My proposition was just to leave --write-uses-list as it is, and let=20
> --show-implementation decide whether "--write-uses-list means to show=20
> all uses" or "--write-uses-list means to show only interface uses".

I really don't like this. --write-uses-list controls whether to write
the uses list or not, I don't like to move decisions on that into
another option.

> Otherwise, if we really want to have a way to show implementation uses=20
> clause but not items declared in the implementation, we can make new=20
> option, like "--write-uses=3Dyes/no/only-interface" and say that=20
> "--write-uses-list" is just a shortcut for "--write-uses=3Dyes". That's=20
> the way how we can keep compatibility.

Yes, good idea.

johannes

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

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

Johannes Berg wrote:
[...]
> 
>>Otherwise, if we really want to have a way to show implementation uses 
>>clause but not items declared in the implementation, we can make new 
>>option, like "--write-uses=yes/no/only-interface" and say that 
>>"--write-uses-list" is just a shortcut for "--write-uses=yes". That's 
>>the way how we can keep compatibility.
> 
> 
> Yes, good idea.
> 

Actually, let's name it "--show-uses=all/interface/no", this way naming 
is a little consistent with --show-implementation. Oh, and 
"--write-uses-list" is a shortcut for "--show-uses=interface" to keep 
compatibility.

Michalis

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

[Johannes B. <joh...@si...>]

Michalis Kamburelis wrote:
> Actually, let's name it "--show-uses=all/interface/no", this way naming
> is a little consistent with --show-implementation. Oh, and
> "--write-uses-list" is a shortcut for "--show-uses=interface" to keep
> compatibility.

Sounds good to me.

johannes

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

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

On Wed, Dec 21, 2005 at 01:59:46PM +0100, Johannes Berg wrote:
> Michalis Kamburelis wrote:
> > Actually, let's name it "--show-uses=all/interface/no", this way naming
> > is a little consistent with --show-implementation. Oh, and
> > "--write-uses-list" is a shortcut for "--show-uses=interface" to keep
> > compatibility.
> 
> Sounds good to me.
> 
> johannes

I'm going to use these parameters.

Mark

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:
>
[..]
> a) prepare another image img/defined_in_implementation.gif (based on 
> e.g. img/private.gif in pasdoc sources)
> 
FYI the images in img are not used in the output, in fact they're not
the same as in the output. I'm putting my image in this directory based
upon the images as used in the output.

Mark

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:
> 
>>Mark de Wever wrote:
>>
> 
> [..]
> 
>>a) prepare another image img/defined_in_implementation.gif (based on 
>>e.g. img/private.gif in pasdoc sources)
>>
> 
> FYI the images in img are not used in the output, in fact they're not
> the same as in the output. I'm putting my image in this directory based
> upon the images as used in the output.
> 

Ups, you're right. Looking at CVS logs, it seems that at the beginning 
images in img/*.gif directory corresponded to include files in 
source/component/*.inc. But then on August 4th, 2003 new version of 
images were committed -- images in source/component/*.inc were updated, 
but their corresponding files in img/*.gif were left outdated...

I just fixed this situation and did some related cleaning that was 
pending. Up-to-date *.gif images are now placed inside 
source/components/images/, along with their corresponding *.gif.inc 
files and a small Makefile to use tools/file_to_pascal_data program to 
convert between *.gif and *.gif.inc files. Old images in img/ and old 
include files in source/component/ are removed now. This should make 
this whole situation cleaner.

(You may have to wait up to 5 hours to see my modifications in public CVS).

Your image for defined_in_implementation.gif should be based on images 
currently used in the output, not on the outdated things in img/ dir, so 
you've done right. Your new image should be added now to 
source/components/images/, and appropriate modification to 
source/components/images/Makefile should be done to make it's 
corresponding *.gif.inc file.

Michalis

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

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

On Thu, Dec 22, 2005 at 09:49:35PM +0100, Michalis Kamburelis wrote:
> Mark de wever wrote:
> >On Thu, Dec 15, 2005 at 09:05:28AM +0100, Michalis Kamburelis wrote:
> >
> >>Mark de Wever wrote:
> >>
> >
> >[..]
> >
> >>a) prepare another image img/defined_in_implementation.gif (based on 
> >>e.g. img/private.gif in pasdoc sources)
> >>
> >
> >FYI the images in img are not used in the output, in fact they're not
> >the same as in the output. I'm putting my image in this directory based
> >upon the images as used in the output.
> >
> 
> Ups, you're right. Looking at CVS logs, it seems that at the beginning 
> images in img/*.gif directory corresponded to include files in 
> source/component/*.inc. But then on August 4th, 2003 new version of 
> images were committed -- images in source/component/*.inc were updated, 
> but their corresponding files in img/*.gif were left outdated...
> 
> I just fixed this situation and did some related cleaning that was 
> pending. Up-to-date *.gif images are now placed inside 
> source/components/images/, along with their corresponding *.gif.inc 
> files and a small Makefile to use tools/file_to_pascal_data program to 
> convert between *.gif and *.gif.inc files. Old images in img/ and old 
> include files in source/component/ are removed now. This should make 
> this whole situation cleaner.

I also used file_to_pascal_data to convert my images.

> (You may have to wait up to 5 hours to see my modifications in public CVS).

Indeed not there yet.

> Your image for defined_in_implementation.gif should be based on images 
> currently used in the output, not on the outdated things in img/ dir, so 
> you've done right. Your new image should be added now to 
> source/components/images/, and appropriate modification to 
> source/components/images/Makefile should be done to make it's 
> corresponding *.gif.inc file.

Attached a sample of how things are going to look with 
--show-uses=all --show-implementation=all
I only added the declaration symbols for the procedures and functions for now.

When --show-implementation<>all the output as it currently is is used.

I (ab)used the legend of the members at the moment, should we have one
legend page with both or two legend pages?

Mark

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

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

Mark de Wever wrote:
[...]
> 
> Attached a sample of how things are going to look with 
> --show-uses=all --show-implementation=all
> I only added the declaration symbols for the procedures and functions for now.
> 
> When --show-implementation<>all the output as it currently is is used.
> 
> I (ab)used the legend of the members at the moment, should we have one
> legend page with both or two legend pages?
> 

I think that one legend page with two tables (first the table titled 
"Visibility of classes/interfaces/objects members" with the previous 
private, protected, etc. rows, and then the 2nd table titled "Where the 
item is declared" (maybe you can propose some better name for it...) 
with 3 rows with your new values "Program", "Unit interface", 
"Implementation"). I think that this will look sensible.

Notes:

1. Maybe the cell for standard visibility "Unit interface" would be 
better left blank ? I.e. you could replace the defined_in_unit_interface 
file with a simple completely transparent GIF image. I just did this 
with GIMP and result looks good...

But it may be just because I'm accustomed to seeing only the things 
visible in the interface, and I like to easily visually "see" the 
difference between "Defined in unit's interface" and the rest of items. 
Decision is up to you.

2. Note that file `defined_in_unit_interface' is without the extension, 
i.e. it's named (and linked as) `defined_in_unit_interface' instead of 
`defined_in_unit_interface.gif'. (Just a minor note, in case you didn't 
know about this and you have some bug :)

3. Note that in your testcase you have two separate "uses" clauses in 
the interface. Sure, pasdoc parses it (by kind of accident), but you 
probably wanted to move the "uses another_unit;" clause to 
implementation section to test this also...

Michalis

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

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

On Thu, Dec 22, 2005 at 11:46:28PM +0100, Michalis Kamburelis wrote:
> Mark de Wever wrote:
> [...]
> >
> >Attached a sample of how things are going to look with 
> >--show-uses=all --show-implementation=all
> >I only added the declaration symbols for the procedures and functions for 
> >now.
> >
> >When --show-implementation<>all the output as it currently is is used.
> >
> >I (ab)used the legend of the members at the moment, should we have one
> >legend page with both or two legend pages?
> >
> 
> I think that one legend page with two tables (first the table titled 
> "Visibility of classes/interfaces/objects members" with the previous 
> private, protected, etc. rows, and then the 2nd table titled "Where the 
> item is declared" (maybe you can propose some better name for it...) 
> with 3 rows with your new values "Program", "Unit interface", 
> "Implementation"). I think that this will look sensible.
> 
> Notes:
> 
> 1. Maybe the cell for standard visibility "Unit interface" would be 
> better left blank ? I.e. you could replace the defined_in_unit_interface 
> file with a simple completely transparent GIF image. I just did this 
> with GIMP and result looks good...
> 
> But it may be just because I'm accustomed to seeing only the things 
> visible in the interface, and I like to easily visually "see" the 
> difference between "Defined in unit's interface" and the rest of items. 
> Decision is up to you.

I'll think about it, note that if you don't use te new switches, the
output remains as it used to be. If other people has an option, please
let me know.

> 2. Note that file `defined_in_unit_interface' is without the extension, 
> i.e. it's named (and linked as) `defined_in_unit_interface' instead of 
> `defined_in_unit_interface.gif'. (Just a minor note, in case you didn't 
> know about this and you have some bug :)

One of the many at the moment :) but thx, a copy and paste error.

> 3. Note that in your testcase you have two separate "uses" clauses in 
> the interface. Sure, pasdoc parses it (by kind of accident), but you 
> probably wanted to move the "uses another_unit;" clause to 
> implementation section to test this also...

yep I move the implementation line up and down every now and then...
BTW I use this accidental feature to also parse the uses in the
implementation... 

Mark

PS next week I won't be behind my computer often so I won't be able to
do a lot or answer emails.

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

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

On Thu, Dec 22, 2005 at 09:49:35PM +0100, Michalis Kamburelis wrote:
> Mark de wever wrote:
> >On Thu, Dec 15, 2005 at 09:05:28AM +0100, Michalis Kamburelis wrote:
> >
> >>Mark de Wever wrote:
> >>
> >
> >[..]
> >
> >>a) prepare another image img/defined_in_implementation.gif (based on 
> >>e.g. img/private.gif in pasdoc sources)
> >>
> >
> >FYI the images in img are not used in the output, in fact they're not
> >the same as in the output. I'm putting my image in this directory based
> >upon the images as used in the output.
> >
> 
> Ups, you're right. Looking at CVS logs, it seems that at the beginning 
> images in img/*.gif directory corresponded to include files in 
> source/component/*.inc. But then on August 4th, 2003 new version of 
> images were committed -- images in source/component/*.inc were updated, 
> but their corresponding files in img/*.gif were left outdated...
> 
> I just fixed this situation and did some related cleaning that was 
> pending. Up-to-date *.gif images are now placed inside 
> source/components/images/, along with their corresponding *.gif.inc 
> files and a small Makefile to use tools/file_to_pascal_data program to 
> convert between *.gif and *.gif.inc files. Old images in img/ and old 
> include files in source/component/ are removed now. This should make 
> this whole situation cleaner.
[..]

Should pasdoc.css be also be put in the same directory so it's also
always updated?

Regards,

Mark de Wever

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

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

Mark de Wever wrote:
> On Thu, Dec 22, 2005 at 09:49:35PM +0100, Michalis Kamburelis wrote:
[...]
>>
>>I just fixed this situation and did some related cleaning that was 
>>pending. Up-to-date *.gif images are now placed inside 
>>source/components/images/, along with their corresponding *.gif.inc 
>>files and a small Makefile to use tools/file_to_pascal_data program to 
>>convert between *.gif and *.gif.inc files. Old images in img/ and old 
>>include files in source/component/ are removed now. This should make 
>>this whole situation cleaner.
> 
> [..]
> 
> Should pasdoc.css be also be put in the same directory so it's also
> always updated?
> 

I think no, source/component/images/ is intended for images (*.gif and 
*.gif.inc), and source/component/images/Makefile to synchronize them.

pasdoc.css and pasdoc.css.inc are inside source/component/, and 
source/component/Makefile is used to synchronize them.

(And there are also source/component/tipue/ files, that are synchronized 
by source/component/tipue/Makefile).

Michalis

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

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

[Johannes B. <joh...@si...>]

On Mon, 2005-12-19 at 08:43 +0100, Mark de Wever wrote:

> When an item defined in the interface has a comment in both the=20
> interface and the implementation, what would people prefer to do.=20
> I think we should give a warning and use the comment in the=20
> implementation, just like the backcomment now does to a normal=20
> 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.

Maybe the comment in the interface could (optionally?) be used as the
abstract if it is short enough (usual rules apply)? Then you could have
some terse description in the interface section and the detailed one
below. Wasn't the main problem people had with this that it cluttered
the interface section too much? A terse abstract could still be useful
there...

Just an idea, I don't have a real opinion on this.

johannes

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

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

On Sat, Dec 17, 2005 at 07:44:28PM +0100, Johannes Berg wrote:
> On Fri, 2005-12-16 at 14:53 +0100, Michalis Kamburelis wrote:
>
[...] 
> 
> Anyway, I digress. I don't think adding it to --write-uses-list makes
> sense either since then you have to use --parse-implementation together
> with that to get full output. In fact, I think I'd prefer the following
> possible settings along with a rename from --parse-implementation to
> --show-implementation:
> 
> --show-implementation       given: default to all
>                         not given: default to nothing
>                   possible values: all,nothing,only-for-interface
> 
> --write-uses-list           given: default to yes
>                         not given: default to no
>                   possible values: yes,no,only-interface
>                             [only-implementation doesn't make sense]
> 
> The reason for renaming from --parse-... to --show-... is that the
> actual parsing is just a detail of what pasdoc needs to do to fulfil the
> goal of showing the comments in the implementation section, and I think
> the command line options should be named after the goal not the process.
> 
> What do you think?

FYI I just read your mail, it arrived after I send my response to Michalis.

I don't have a strong opinion about the name, but the parameters
indeed seem to describe the goal not the process. If people agree on
this I'll use these parameters including the extra options for the
parameters and their options.

Mark de Wever