keydb.[ch], internal docs

[Werner Koch]

Hi Neal,

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:

--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:

--8<---------------cut here---------------start------------->8---
/* Enumerate some secret keys (specifically, those specified with
   --default-key and --try-secret-key).
   For detailed documentation see keydb.h.  */
 gpg_error_t
 enum_secret_keys (void **context, PKT_public_key *sk)
--8<---------------cut here---------------end--------------->8---


BTW, it is likely that there will soon be a project which requires us to
formalize the way we do internal documentation; thus we need to
something here anyway.


Salam-Shalom,

   Werner


-- 
Die Gedanken sind frei.  Ausnahmen regelt ein Bundesgesetz.