From d0f01ef61a0b9ffe7f7252e08917ed284e2f0b9e Mon Sep 17 00:00:00 2001
Message-Id: <d0f01ef61a0b9ffe7f7252e08917ed284e2f0b9e.1715157694.git.mdw@distorted.org.uk>
From: Mark Wooding <mdw@chiark.greenend.org.uk>
Date: Sun, 7 Aug 2011 14:05:37 +0100
Subject: [PATCH] protogen: a bit more generated docs tidying
Organization: Straylight/Edgeware

From: Richard Kettlewell <rjk@terraraq.org.uk>

---
 lib/client-stubs.c  |  3 +++
 lib/client-stubs.h  |  5 +++++
 lib/client.h        |  3 +++
 lib/eclient-stubs.c |  3 +++
 lib/eclient-stubs.h |  5 +++++
 lib/eclient.h       |  2 ++
 scripts/protocol    | 16 ++++++++++++++++
 7 files changed, 37 insertions(+)

diff --git a/lib/client-stubs.c b/lib/client-stubs.c
index 6aaa559..10a1fb2 100644
--- a/lib/client-stubs.c
+++ b/lib/client-stubs.c
@@ -20,6 +20,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/client-stubs.c
+ * @brief Generated client API implementation
+ */
 
 int disorder_adopt(disorder_client *c, const char *id) {
   return disorder_simple(c, NULL, "adopt", id, (char *)NULL);
diff --git a/lib/client-stubs.h b/lib/client-stubs.h
index 07312b4..1962df2 100644
--- a/lib/client-stubs.h
+++ b/lib/client-stubs.h
@@ -22,6 +22,11 @@
  */
 #ifndef CLIENT_STUBS_H
 #define CLIENT_STUBS_H
+/** @file lib/client-stubs.h
+ * @brief Generated client API
+ *
+ * Don't include this file directly - use @ref client.h instead.
+ */
 
 /** @brief Adopt a track
  *
diff --git a/lib/client.h b/lib/client.h
index 4210b60..2513a89 100644
--- a/lib/client.h
+++ b/lib/client.h
@@ -18,6 +18,9 @@
 /** @file lib/client.h
  * @brief Simple C client
  *
+ * See @ref lib/client-stubs.h for the (generated) per-command entry
+ * points.
+ *
  * See @ref lib/eclient.h for an asynchronous-capable client
  * implementation.
  */
diff --git a/lib/eclient-stubs.c b/lib/eclient-stubs.c
index b4e37d6..63f5163 100644
--- a/lib/eclient-stubs.c
+++ b/lib/eclient-stubs.c
@@ -20,6 +20,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/client-stubs.c
+ * @brief Generated asynchronous client API implementation
+ */
 
 int disorder_eclient_adopt(disorder_eclient *c, disorder_eclient_no_response *completed, const char *id, void *v) {
   return simple(c, no_response_opcallback, (void (*)())completed, v, "adopt", id, (char *)0);
diff --git a/lib/eclient-stubs.h b/lib/eclient-stubs.h
index 2475034..af3b389 100644
--- a/lib/eclient-stubs.h
+++ b/lib/eclient-stubs.h
@@ -22,6 +22,11 @@
  */
 #ifndef ECLIENT_STUBS_H
 #define ECLIENT_STUBS_H
+/** @file lib/client-stubs.h
+ * @brief Generated asynchronous client API
+ *
+ * Don't include this file directly - use @ref client.h instead.
+ */
 
 /** @brief Adopt a track
  *
diff --git a/lib/eclient.h b/lib/eclient.h
index 371af13..876e2c6 100644
--- a/lib/eclient.h
+++ b/lib/eclient.h
@@ -17,6 +17,8 @@
  */
 /** @file lib/eclient.h
  * @brief Client code for event-driven programs
+ *
+ * See @ref lib/eclient-stubs.h for the (generated) per-command entry points.
  */
 
 #ifndef ECLIENT_H
diff --git a/scripts/protocol b/scripts/protocol
index 9e7be9d..dec33e2 100755
--- a/scripts/protocol
+++ b/scripts/protocol
@@ -480,17 +480,33 @@ our @gpl = ("/*\n",
 push(@h, @generated, @gpl,
      "#ifndef CLIENT_STUBS_H\n",
      "#define CLIENT_STUBS_H\n",
+     "/** \@file lib/client-stubs.h\n",
+     " * \@brief Generated client API\n",
+     " *\n",
+     " * Don't include this file directly - use \@ref lib/client.h instead.\n",
+     " */\n",
      "\n");
 
 push(@c, @generated, @gpl,
+     "/** \@file lib/client-stubs.c\n",
+     " * \@brief Generated client API implementation\n",
+     " */\n",
      "\n");
 
 push(@ah, @generated, @gpl,
      "#ifndef ECLIENT_STUBS_H\n",
      "#define ECLIENT_STUBS_H\n",
+     "/** \@file lib/client-stubs.h\n",
+     " * \@brief Generated asynchronous client API\n",
+     " *\n",
+     " * Don't include this file directly - use \@ref lib/eclient.h instead.\n",
+     " */\n",
      "\n");
 
 push(@ac, @generated, @gpl,
+     "/** \@file lib/client-stubs.c\n",
+     " * \@brief Generated asynchronous client API implementation\n",
+     " */\n",
      "\n");
 
 # The protocol ----------------------------------------------------------------
-- 
[mdw]