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

Re: [PATCH] svn_io_check_path's docstring ambiguous?

From: Karl Fogel <kfogel_at_red-bean.com>
Date: Fri, 02 May 2008 11:21:25 -0400

Daniel Shahaf <d.s_at_daniel.shahaf.co.il> writes:
> svn_io_check_path's docstring reads:
>
> [...]
>
> 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:
>
> [...]
>
> Proposed fix:
>
> [...]

+1, and the new doc string does seem to match the current behavior. But
as long as we're fixing the doc string, let's put it in the active voice,
which is slightly easier to absorb I think:

Index: subversion/include/svn_io.h
===================================================================
--- subversion/include/svn_io.h (revision 30934)
+++ subversion/include/svn_io.h (working copy)
@@ -73,21 +73,20 @@
   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, set @a *kind to @c svn_node_file.
  *
- * If @a path is a file, @a *kind is set to @c svn_node_file.
+ * If @a path is a directory, set @a *kind to @c svn_node_dir.
  *
- * 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
+ * If @a path does not exist in its final component, set @a *kind to
  * @c svn_node_none.
  *
- * If intermediate directories on the way to @a path don't exist, an
- * error is returned, and @a *kind's value is undefined.
+ * If intermediate directories on the way to @a path don't exist, return
+ * an error, with @a *kind's value undefined.
  *
+ * Otherwise, set @a *kind to @c svn_node_unknown.
+ *
  * Use @a pool for temporary allocations.
  */
 svn_error_t *svn_io_check_path(const char *path,

---------------------------------------------------------------------
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 17:21:43 CEST

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