Re: svn commit: rev 4200 - in branches/issue-951-dev/subversion: include libsvn_wc clients/cmdline tests/clients/cmdline/getopt_tests_data

[Garrett Rooney <ro...@electricjellyfish.net>]

> +/* Modify a working copy directory DIR, changing any
> +   repository URLs that begin with FROM to begin with TO instead,
> +   recursing into subdirectories if RECURSE is true. */
> +svn_error_t *
> +svn_client_relocate (const char *dir,
> +                     const char *from,
> +                     const char *to,
> +                     svn_boolean_t recurse,
> +                     apr_pool_t *pool);
> +
> +

hey, i spent an annoyingly long amount of time putting the comments in 
that file into doxygen format and now you've gone and cluttered it up 
again.

just a friendly reminder to doxygenate it before you merge it into 
/trunk.

the changes themself look cool...  can't wait to have the feature.

thanks,

-garrett


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: svn commit: rev 4200 - in branches/issue-951-dev/subversion: include libsvn_wc clients/cmdline tests/clients/cmdline/getopt_tests_data

[Justin Erenkrantz <je...@apache.org>]

--On Sunday, December 29, 2002 10:26 AM -0600 Karl Fogel 
<kf...@newton.ch.collab.net> wrote:

> It's just that we have had a stylistic convention of introducing
> parameters in the prose.  Personally, I like this way, because it
> often makes it easier to see how the paramaters relate to each other
> and to the overall purpose of the function.  Capitalizing them was
> just a way of making them stand out as parameters; the doxygenation
> is just to make them stand out in a markup-y way instead.

If you don't use the @param tag, you have no way of indicating that 
is the parameter.  The only thing is that it is emphasized in the 
brief description.  I think that's a bit too subtle.  But, I won't 
belabor the point too much though.

As you can see in my commit to the branch, you can do both approaches 
in the same comment.  =)  -- justin

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: svn commit: rev 4200 - in branches/issue-951-dev/subversion: include libsvn_wc clients/cmdline tests/clients/cmdline/getopt_tests_data

[Karl Fogel <kf...@newton.ch.collab.net>]

Garrett Rooney <ro...@electricjellyfish.net> writes:
> i think we were avoiding them because when branko was coming up with
> the doxygen config we would use he was trying to stick as closely to
> the existing style as possible.  personally, i think that in most
> cases, the existing comments have explanations for all the params, so
> having extra doxygen markup for them is just cluttering up the
> headers. unless having those tags allows doxygen to generate better
> output for some reason?

It's just that we have had a stylistic convention of introducing
parameters in the prose.  Personally, I like this way, because it
often makes it easier to see how the paramaters relate to each other
and to the overall purpose of the function.  Capitalizing them was
just a way of making them stand out as parameters; the doxygenation is
just to make them stand out in a markup-y way instead.

-K, who can read @param-style docs but is not a fan :-)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: svn commit: rev 4200 - in branches/issue-951-dev/subversion: include libsvn_wc clients/cmdline tests/clients/cmdline/getopt_tests_data

[Garrett Rooney <ro...@electricjellyfish.net>]

On Sunday, December 29, 2002, at 01:51 AM, Justin Erenkrantz wrote:

> --On Saturday, December 28, 2002 8:21 PM -0500 Garrett Rooney 
> <ro...@electricjellyfish.net> wrote:
>
>> hey, i spent an annoyingly long amount of time putting the comments
>> in that file into doxygen format and now you've gone and cluttered
>> it up again.
>>
>> just a friendly reminder to doxygenate it before you merge it into
>> /trunk.
>
> Sure - no problem.  Out of curiousity, why do we not use @param's? 
> Shouldn't we be using them?  See APR's use of doxygen for an idea of 
> what I'm getting at.  -- justin

i think we were avoiding them because when branko was coming up with 
the doxygen config we would use he was trying to stick as closely to 
the existing style as possible.  personally, i think that in most 
cases, the existing comments have explanations for all the params, so 
having extra doxygen markup for them is just cluttering up the headers. 
  unless having those tags allows doxygen to generate better output for 
some reason?

so yeah, i guess my answer is "ask branko why he didn't use them" ;-)

-garrett


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: svn commit: rev 4200 - in branches/issue-951-dev/subversion: include libsvn_wc clients/cmdline tests/clients/cmdline/getopt_tests_data

[Justin Erenkrantz <je...@apache.org>]

--On Saturday, December 28, 2002 8:21 PM -0500 Garrett Rooney 
<ro...@electricjellyfish.net> wrote:

> hey, i spent an annoyingly long amount of time putting the comments
> in that file into doxygen format and now you've gone and cluttered
> it up again.
>
> just a friendly reminder to doxygenate it before you merge it into
> /trunk.

Sure - no problem.  Out of curiousity, why do we not use @param's? 
Shouldn't we be using them?  See APR's use of doxygen for an idea of 
what I'm getting at.  -- justin

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org