[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

[PATCH] svn_io_check_path's docstring ambiguous?

From: Daniel Shahaf <d.s_at_daniel.shahaf.co.il>
Date: Fri, 2 May 2008 16:32:16 +0300 (IDT)

svn_io_check_path's docstring reads:

    /** Determine the @a kind of @a path.
     *
     * If utf8-encoded @a path exists, set @a *kind to the appropriate kind,
     * else set it to @c svn_node_unknown.
       ^^^^ [1]
     *
     * If @a path is a file, @a *kind is set to @c svn_node_file.
     *
     * If @a path is a directory, @a *kind is set to @c svn_node_dir.
     *
     * If @a path does not exist in its final component, @a *kind is set to
       ^^ [3]
     * @c svn_node_none.
     *
     * If intermediate directories on the way to @a path don't exist, an
       ^^ [2]
     * error is returned, and @a *kind's value is undefined.
     *
     * Use @a pool for temporary allocations.
     */
    svn_error_t *svn_io_check_path(const char *path,
                                   svn_node_kind_t *kind,
                                   apr_pool_t *pool);

As I read it, this specifies three non-exclusive cases:

    [1] path does not exist => svn_node_unknown
    [2] path's parent is absent => *undefined*
    [3] path's parent exist
        && path does not exist => svn_node_none

After discussion with Kamesh on IRC, we assumed that the intended
behaviour is as documented in svn_node_kind_t:

    /** The various types of nodes in the Subversion filesystem. */
    typedef enum
    {
      /** absent */
      svn_node_none,
    ...
      /** something's here, but we don't know what */
      svn_node_unknown
    } svn_node_kind_t;

Proposed fix:

    Index: subversion/include/svn_io.h
    ===================================================================
    --- subversion/include/svn_io.h (revision 30929)
    +++ subversion/include/svn_io.h (working copy)
    @@ -73,11 +73,8 @@
       svn_boolean_t special;
     } svn_io_dirent_t;
     
    -/** Determine the @a kind of @a path.
    +/** Determine the @a kind of @a path. @a path should be UTF-8 encoded.
      *
    - * If utf8-encoded @a path exists, set @a *kind to the appropriate kind,
    - * else set it to @c svn_node_unknown.
    - *
      * If @a path is a file, @a *kind is set to @c svn_node_file.
      *
      * If @a path is a directory, @a *kind is set to @c svn_node_dir.
    @@ -88,6 +85,8 @@
      * If intermediate directories on the way to @a path don't exist, an
      * error is returned, and @a *kind's value is undefined.
      *
    + * Otherwise, @a *kind is set to @c svn_node_unknown.
    + *
      * Use @a pool for temporary allocations.
      */
     svn_error_t *svn_io_check_path(const char *path,

Opinions?

Daniel

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe_at_subversion.tigris.org
For additional commands, e-mail: dev-help_at_subversion.tigris.org
Received on 2008-05-02 15:32:42 CEST

This is an archived mail posted to the Subversion Dev mailing list.