Re: To Greg Stein

Greg Stein wrote on Mon, 18 Aug 2008 at 12:41 -0700:
> On Mon, Aug 18, 2008 at 10:27 AM, Daniel Shahaf <d.s_at_daniel.shahaf.name> wrote:
> > Greg Stein wrote on Mon, 18 Aug 2008 at 08:05 -0700:
> >> As I've been poring over svn_wc.h, I've been thinking that we need
> >> svn_deprecated.h and move all of the function signatures and types
> >> into that file. Let them all sit there, undocumented ("want doc? look
> >
> > I like having the diff'ed doc-strings [1] available, using them is
> > easier than reading doc-strings on two branches and doing a mental diff.
> >
> > In other words, I think the doc-strings are useful :)
>
> Agreed. But I'm talking about the *deprecated* functions. Why do they
> need docstrings?
>

* So people looking to upgrade to the non-deprecated version know what
  the differences are.

* Have everything in one place. If I wrote code against the 1.4 API, and
  then upgraded *some* functions to their 1.5 API versions, and then
  upgraded *some* other functions to their 1.6 API versions ...

  I wouldn't want to have to look in three different include/ directories
  whenever I try to understand the code I wrote. :)

> "We don't want you using these functions, so we're not going to document them."
>

"We don't want you using these functions, so we mark them as @deprecated.
We trust you to know not to use them in new code."

(And we tell you to define SVN_DEPRECATED_H if you want to find all calls
to deprecated functions.)

> Cheers,
> -g
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe_at_subversion.tigris.org
For additional commands, e-mail: dev-help_at_subversion.tigris.org
Received on 2008-08-18 22:12:18 CEST