You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Edmund Wong <ed...@kdtc.net> on 2009/04/17 04:12:34 UTC
docstring clarification
Hi,
I've come across a docstring which I think is incomplete as
the sentence itself doesn't make any sense (at least, not to
me).
Can someone clarify the following? It's in include/svn_wc.h,
docstring for the field *access in typedef struct
svn_wc_conflict_description_t.
/** If not NULL, an open working copy access baton to either the
* path itself (if @c path is a directory), or to the parent
* directory (if @c path is a file.)
Thanks
Edmund
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1760432
Re: docstring clarification
Posted by Greg Stein <gs...@gmail.com>.
On Mon, Apr 20, 2009 at 02:27, Gavin 'Beau' Baumanis
<ga...@thespidernet.com> wrote:
> Hi Everyone,
>
> As Edmund goes through the header files and finds things in the comments
> that he doesn't understand - there is always a nice succinct reply from
> "someone" that clears up his understanding of the comment in question.
>
> Would it not be appropriate to change the documentation to be the provided
> succinct response, so that it might be clear(er) for all who visit the code
> next time around?
Definitely!
Though, in this case, the doc-change is "@deprecated" and deletion of
the bulk of the text :-)
Cheers,
-g
>
> Gavin.
>
>
>
> On 19/04/2009, at 3:40 AM, Greg Stein wrote:
>
>> On Sat, Apr 18, 2009 at 17:27, Edmund Wong <ed...@kdtc.net> wrote:
>>>
>>> Arfrever Frehtes Taifersar Arahesis wrote:
>>>
>>>>> /** If not NULL, an open working copy access baton to either the
>>>>> * path itself (if @c path is a directory), or to the parent
>>>>> * directory (if @c path is a file.)
>>>>
>>>> This doc string is complete.
>>>> If 'access' is NULL, then it doesn't point to anything.
>>>> If 'access' isn't NULL, then it points to an open working copy access
>>>> baton.
>>>>
>>> Ah. Now I understand. 'to' is being used as a verb, right?
>>
>> Yes. As in "points to" or "opened to" or something like that.
>>
>> Access batons are associated with directories, which is why the
>> docstring clarifies the baton based on the path's kind.
>>
>> Cheers,
>> -g
>>
>> ------------------------------------------------------
>>
>> http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1793385
>
>
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1824216
Re: docstring clarification
Posted by Edmund Wong <ed...@kdtc.net>.
Branko Cibej wrote:
>
> I think it's hardly worth mentioning explicitly. How else do you create
> sensible patches if not by understanding the code in the first place?
>
Well, I was thinking more or less of understanding Subversion
and its commands. But like you said, it's obviously required.
What was I thinking? duh...
Edmund
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1892133
Re: docstring clarification
Posted by Branko Cibej <br...@xbc.nu>.
Edmund Wong wrote:
> Btw, as a suggestion, I think 'understanding SVN' should
> also be a requirement in order to be a dev on subversion.
> It's unwritten, sure and possibly darn obvious; but, I didn't
> think it was.
>
I think it's hardly worth mentioning explicitly. How else do you create
sensible patches if not by understanding the code in the first place?
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1847345
Re: docstring clarification
Posted by Edmund Wong <ed...@kdtc.net>.
Gavin Baumanis wrote:
> Hi Everyone,
>
> As Edmund goes through the header files and finds things in the
> comments that he doesn't understand - there is always a nice succinct
> reply from "someone" that clears up his understanding of the comment
> in question.
>
> Would it not be appropriate to change the documentation to be the
> provided succinct response, so that it might be clear(er) for all who
> visit the code next time around?
It definitely would; though, might it 'ruin' its appeal to
'hard core' devs? Reading the doc strings does help me
understand the code; but, only to a certain point. Sometimes
I just find the documentation overwhelming (possibly because
of my lack of a strong C background). As an anecdote,
I was surprised to see something like :
svn_wc_get_prop_diffs(apr_array_header_t **propchanges..
A pointer to a pointer to propchanges which is of the type
apr_array_header_t, right? Needless to say, I've got a long
ways to fully understand the code.
Btw, as a suggestion, I think 'understanding SVN' should
also be a requirement in order to be a dev on subversion.
It's unwritten, sure and possibly darn obvious; but, I didn't
think it was.
Anyway, thanks for the help in understanding the code,
well, at least the headers.
Edmund
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1825079
Re: docstring clarification
Posted by Gavin Baumanis <ga...@thespidernet.com>.
Hi Everyone,
As Edmund goes through the header files and finds things in the
comments that he doesn't understand - there is always a nice succinct
reply from "someone" that clears up his understanding of the comment
in question.
Would it not be appropriate to change the documentation to be the
provided succinct response, so that it might be clear(er) for all who
visit the code next time around?
Gavin.
On 19/04/2009, at 3:40 AM, Greg Stein wrote:
> On Sat, Apr 18, 2009 at 17:27, Edmund Wong <ed...@kdtc.net> wrote:
>> Arfrever Frehtes Taifersar Arahesis wrote:
>>
>>>> /** If not NULL, an open working copy access baton to either the
>>>> * path itself (if @c path is a directory), or to the parent
>>>> * directory (if @c path is a file.)
>>>
>>> This doc string is complete.
>>> If 'access' is NULL, then it doesn't point to anything.
>>> If 'access' isn't NULL, then it points to an open working copy
>>> access baton.
>>>
>> Ah. Now I understand. 'to' is being used as a verb, right?
>
> Yes. As in "points to" or "opened to" or something like that.
>
> Access batons are associated with directories, which is why the
> docstring clarifies the baton based on the path's kind.
>
> Cheers,
> -g
>
> ------------------------------------------------------
> http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1793385
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1815027
Re: docstring clarification
Posted by Greg Stein <gs...@gmail.com>.
On Sat, Apr 18, 2009 at 17:27, Edmund Wong <ed...@kdtc.net> wrote:
> Arfrever Frehtes Taifersar Arahesis wrote:
>
>>> /** If not NULL, an open working copy access baton to either the
>>> * path itself (if @c path is a directory), or to the parent
>>> * directory (if @c path is a file.)
>>
>> This doc string is complete.
>> If 'access' is NULL, then it doesn't point to anything.
>> If 'access' isn't NULL, then it points to an open working copy access baton.
>>
> Ah. Now I understand. 'to' is being used as a verb, right?
Yes. As in "points to" or "opened to" or something like that.
Access batons are associated with directories, which is why the
docstring clarifies the baton based on the path's kind.
Cheers,
-g
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1793385
Re: docstring clarification
Posted by Edmund Wong <ed...@kdtc.net>.
Arfrever Frehtes Taifersar Arahesis wrote:
>> /** If not NULL, an open working copy access baton to either the
>> * path itself (if @c path is a directory), or to the parent
>> * directory (if @c path is a file.)
>
> This doc string is complete.
> If 'access' is NULL, then it doesn't point to anything.
> If 'access' isn't NULL, then it points to an open working copy access baton.
>
Ah. Now I understand. 'to' is being used as a verb, right?
Edmund
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1791580
Re: docstring clarification
Posted by Arfrever Frehtes Taifersar Arahesis <Ar...@GMail.Com>.
2009-04-17 06:12:34 Edmund Wong napisał(a):
> Hi,
>
> I've come across a docstring which I think is incomplete as
> the sentence itself doesn't make any sense (at least, not to
> me).
>
> Can someone clarify the following? It's in include/svn_wc.h,
> docstring for the field *access in typedef struct
> svn_wc_conflict_description_t.
>
> /** If not NULL, an open working copy access baton to either the
> * path itself (if @c path is a directory), or to the parent
> * directory (if @c path is a file.)
This doc string is complete.
If 'access' is NULL, then it doesn't point to anything.
If 'access' isn't NULL, then it points to an open working copy access baton.
--
Arfrever Frehtes Taifersar Arahesis