Re: svn commit: r40073 - trunk/subversion/libsvn_wc

[Julian Foad <ju...@btopenworld.com>]

Bert Huijben wrote:
> Author: rhuijben
> Date: Fri Oct 16 03:31:53 2009
> New Revision: 40073
> 
> Log:
> * subversion/libsvn_wc/wc_db.h
>   (svn_wc__db_status_t): Add some status details
>   (depth question): Add some more docs.
>   (svn_wc__db_op_set_props): Documentation fix.
>   (svn_wc__db_read_info: argument order): Add answer.
>   (svn_wc__db_global_commit): Collapse question in docs.

> Modified: trunk/subversion/libsvn_wc/wc_db.h
> URL: http://svn.collab.net/viewvc/svn/trunk/subversion/libsvn_wc/wc_db.h?pathrev=40073&r1=40072&r2=40073
> ==============================================================================
> --- trunk/subversion/libsvn_wc/wc_db.h	Fri Oct 16 03:24:48 2009	(r40072)
> +++ trunk/subversion/libsvn_wc/wc_db.h	Fri Oct 16 03:31:53 2009	(r40073)
> @@ -171,10 +171,16 @@ typedef enum {
>  
>      /* The node has been added (potentially obscuring a delete or move of
>         the BASE node; see BASE_SHADOWED param). The text will be marked as
> -       modified, and if properties exist, they will be marked as modified. */
> +       modified, and if properties exist, they will be marked as modified. 
> +
> +       svn_wc__db_read_status() will return this status for all added,
> +       copied and moved_here nodes. In this case you can use
> +       svn_wc__db_scan_addition() to get a more detailed status */
>      svn_wc__db_status_added,

As I mentioned on IRC, please put docs about how certain functions
behave in those functions' own doc strings. This comment could say
something like "Sometimes status_added means any of added, moved-here or
copied-here. See individual functions for clarification." That will
still sound sub-optimal but at least it will be accurate.
 
[...]
@@ -1370,14 +1382,8 @@ svn_wc__db_global_relocate(svn_wc__db_t 
>  
>  /* ### docco
>  
> -   ### collapse the WORKING and ACTUAL tree changes down into BASE.
> -
> -   ### BH: This probably needs an exclude filter and some kind of depth
> -   ###   support, before it can replace other code.
> -   ### GS: nope. the intent is to call this once per committed node. each
> -   ###   node is committed transactionally. upper layers can deal with
> -   ###   depth and exclusion. this function will combine the functionality
> -   ###   of process_committed_leaf() and log_do_committed().
> +   ### collapse the WORKING and ACTUAL tree changes down into BASE, called
> +       for each committed node.

Rather than "called for each committed node", it would be useful to
state more explicitly what GS' comment was getting at: This function
commits the specified node only, not recursively if it's a directory.

If either of you are able to write at least brief doc strings for the
static functions process_committed_leaf() and log_do_committed(), that
would be marvellous. I expect they've been around for years but at this
point you've probably got a better idea than anybody of what they're
for.

- Julian

------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=2408238