protogen: a bit more generated docs tidying

diff --git a/lib/client-stubs.c b/lib/client-stubs.c
index 6aaa559..10a1fb2 100644 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
--- 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 (executable)
--- 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 ----------------------------------------------------------------