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