keydb.[ch], internal docs

[Neal H. Walfield]

At Wed, 16 Sep 2015 17:21:37 +0200,
Werner Koch wrote:
> I noticed that you greatly improved the documentation of g10/keydb.c - 
> very good.  For some functions you moved the comment from keydb.c to
> keydb.h.  For example in keydb.c we have:

FWIW, I moved the comments for the public APIs (not static functions).

> --8<---------------cut here---------------start------------->8---
>  /* For documentation see keydb.h.  */
>  gpg_error_t
>  enum_secret_keys (void **context, PKT_public_key *sk)
> --8<---------------cut here---------------end--------------->8---
> 
> and in keydb.h:
> 
> --8<---------------cut here---------------start------------->8---
> /* Enumerate some secret keys (specifically, those specified with
>    --default-key and --try-secret-key).  Use the following procedure:
> 
>     1) Initialize a void pointer to NULL
>   [...long and detailed description...]
>  */
> gpg_error_t enum_secret_keys (void **context, PKT_public_key *sk);
> --8<---------------cut here---------------end--------------->8---
> 
> Not beeing a C++ ahcker, I am used to look directly at the code and not
> to switch back and forth between .c and .h.  Thus I would prefer to have
> at least a short comment in the .c file to make it easier to understand
> what it is about.  I know this raises the problem of syncing code and
> comments but it is really helpful for quick reading.  What about this:

I didn't realize that this is a C++ thing.  I picked it up from glibc.

The basic idea (or at least what I find appealing about it) is that it
places all of the documentation for a particular module is in a single
place without the noise of the implementations or other internal
functions.  The trade-off is that the documentation is clearly less
accessible when looking at some particular function's implementation.
Personally, I find that the advantage of this approach much out weighs
the disadvantage.  Does this explanation change your opinion at all?

Perhaps it is possible to configure emacs so that find-tag also visits
prototypes.  I haven't investigated this.

Neal