Jim Blandy <jimb@zwingli.cygnus.com> writes:
> kfogel@tigris.org writes:
> > * svn_fs.h (svn_fs_delete): Doc fix -- promise specific errors, so we
> > can test for them.
>
> Yes, this is a fine thing to do.
>
> Ideally, the documentation for each function would explain exactly
> which errors it can produce. In practice, however, there usually ends
> up being a sizeable variety of errors that might be generated by
> low-level functions used everywhere (e.g., SVN_ERR_BERKELEY_DB), so
> you end up also making blanket statements like: "Any function in this
> interface could generate the following errors: ..."
>
> However, when there are certain errors that have clear relevance to
> the operation (e.g., SVN_ERR_FS_NOT_FOUND, or
> SVN_ERR_FS_DIR_NOT_EMPTY), then those should be documented.
>
> I didn't document these from the beginning because I wasn't sure I
> could tell what I would need. The errors might be more orderly if I
> had, tho.
+1 on everything Jim says above.
When you're going to write tests for specific errors, that's usually
the right time to document that they might be returned.
Received on Sat Oct 21 14:36:25 2006