protogen: a bit more generated docs tidying

diff --git a/lib/client-stubs.c b/lib/client-stubs.c
index 6aaa5595965f12bf1e8ae38c2a3fe6a3ad7e0ef8..10a1fb2e218741190fc11bbd53d10291e859a1bf 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 07312b41119a6cb304abd356af5b80c6195942c3..1962df2799ddfa5163ac0acd19121158c980788c 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 4210b60b14159ea05b9c248cd2f10670f0d8bc42..2513a89e382d756f4e8b1e1bf8c174d19ee521bd 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 b4e37d6e4087fd6fa1052d5c44aea3be9b721c2d..63f5163d35b0cc4488292cb6769480eb99c0e08d 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 2475034ac0f8be4ef286bd835e9678a2d8128d57..af3b389f0d180f298a0dc5df4fd149834cbd8d2a 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 371af135d7f1eb209e4351a656f59b988fbf47ed..876e2c6d3af17c774f8d37f7f5928834fc49a1bb 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 9e7be9dc75d2ce0a4b6666a1457ecc9c3c375b97..dec33e26be4c3cf3227612f4295a6a325565e1ec 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 ----------------------------------------------------------------