Add --function= arg to doc_extract so we can use it on normal ccan C

[ccan] / tools / doc_extract.c

diff --git a/tools/doc_extract.c b/tools/doc_extract.c
index a40e3b1ad0a0ebb1809ecd93fa7a95e8a41c62f7..b1e85d7b0abe6511d0df39f283aa39ccce4ccf3e 100644 (file)
--- a/tools/doc_extract.c
+++ b/tools/doc_extract.c
@@ -8,15 +8,18 @@
 #include <sys/stat.h>
 #include <fcntl.h>
 #include <stdbool.h>
-#include "talloc/talloc.h"
-#include "string/string.h"
+#include <ccan/talloc/talloc.h>
+#include <ccan/str/str.h>
+#include <ccan/str_talloc/str_talloc.h>
+#include <ccan/grab_file/grab_file.h>
+#include "tools.h"
 
 static char **grab_doc(const char *fname)
 {
        char *file;
        char **lines, **ret;
        unsigned int i, num;
-       bool printing = false, printed = false;
+       bool printing = false;
 
        file = grab_file(NULL, fname, NULL);
        if (!file)
@@ -28,8 +31,8 @@ static char **grab_doc(const char *fname)
        for (i = 0; lines[i]; i++) {
                if (streq(lines[i], "/**")) {
                        printing = true;
-                       if (printed++)
-                               talloc_append_string(ret[num], "\n");
+                       if (num != 0)
+                               talloc_append_string(ret[num-1], "\n");
                } else if (streq(lines[i], " */")) 
                        printing = false;
                else if (printing) {
@@ -51,7 +54,7 @@ static bool is_blank(const char *line)
        return line && line[strspn(line, " \t\n")] == '\0';
 }
 
-static bool is_section(const char *line)
+static bool is_section(const char *line, bool maybe_one_liner)
 {
        unsigned int len;
 
@@ -59,21 +62,42 @@ static bool is_section(const char *line)
        if (len == 0)
                return false;
 
+       if (line[len] != ':')
+               return false;
+
+       /* If it can be a one-liner, a space is sufficient.*/
+       if (maybe_one_liner && (line[len+1] == ' ' || line[len+1] == '\t'))
+               return true;
+
        return line[len] == ':' && is_blank(line+len+1);
 }
 
+/* Summary line is form '<identifier> - ' */
+static bool is_summary_line(const char *line)
+{
+       unsigned int id_len;
+
+       id_len = strspn(line, IDENT_CHARS);
+       if (id_len == 0)
+               return false;
+       if (!strstarts(line + id_len, " - "))
+               return false;
+
+       return true;
+}
 
 static bool end_section(const char *line)
 {
-       return !line || is_section(line);
+       return !line || is_section(line, true) || is_summary_line(line);
 }
 
-static unsigned int find_section(char **lines, const char *name)
+static unsigned int find_section(char **lines, const char *name,
+                                bool maybe_one_liner)
 {
        unsigned int i;
 
        for (i = 0; lines[i]; i++) {
-               if (!is_section(lines[i]))
+               if (!is_section(lines[i], maybe_one_liner))
                        continue;
                if (strncasecmp(lines[i], name, strlen(name)) != 0)
                        continue;
@@ -83,14 +107,41 @@ static unsigned int find_section(char **lines, const char *name)
        return i;
 }
 
+/* function is NULL if we don't care. */
+static unsigned int find_summary(char **lines, const char *function)
+{
+       unsigned int i;
+
+       for (i = 0; lines[i]; i++) {
+               if (!is_summary_line(lines[i]))
+                       continue;
+               if (function) {
+                       if (!strstarts(lines[i], function))
+                               continue;
+                       if (!strstarts(lines[i] + strlen(function), " - "))
+                               continue;
+               }
+               break;
+       }
+       return i;
+}
+
+
 int main(int argc, char *argv[])
 {
        unsigned int i;
        const char *type;
+       const char *function = NULL;
 
        if (argc < 3)
-               errx(1, "Usage: doc_extract TYPE <file>...\n"
-                    "Where TYPE is author|licence|maintainer|summary|description|example|all");
+               errx(1, "Usage: doc_extract [--function=<funcname>] TYPE <file>...\n"
+                    "Where TYPE is functions|author|licence|maintainer|summary|description|example|all");
+
+       if (strstarts(argv[1], "--function=")) {
+               function = argv[1] + strlen("--function=");
+               argv++;
+               argc--;
+       }
 
        type = argv[1];
        for (i = 2; i < argc; i++) {
@@ -98,18 +149,33 @@ int main(int argc, char *argv[])
                char **lines = grab_doc(argv[i]);
 
                if (!lines[0])
-                       errx(1, "No documentation in file");
+                       errx(1, "No documentation in file %s", argv[i]);
+
+               if (function) {
+                       /* Allow us to trawl multiple files for a function */
+                       line = find_summary(lines, function);
+                       if (!lines[line])
+                               continue;
 
+                       /* Trim to just this function then. */
+                       lines += line;
+                       lines[find_summary(lines+1, NULL)] = NULL;
+               }
                /* Simple one-line fields. */
                if (streq(type, "author")
                    || streq(type, "maintainer")
                    || streq(type, "licence")) {
-                       line = find_section(lines, type);
+                       line = find_section(lines, type, true);
                        if (lines[line]) {
-                               if (!lines[line+1])
-                                       errx(1, "Malformed %s, end of file",
-                                            type);
-                               puts(lines[line+1]);
+                               const char *p = strchr(lines[line], ':') + 1;
+                               p += strspn(p, " \t\n");
+                               if (p[0] == '\0') {
+                                       /* Must be on next line. */
+                                       if (end_section(lines[line+1]))
+                                               errx(1, "Malformed %s", type);
+                                       puts(lines[line+1]);
+                               } else
+                                       puts(p);
                        }
                } else if (streq(type, "summary")) {
                        /* Summary comes after - on first line. */
@@ -128,7 +194,7 @@ int main(int argc, char *argv[])
                        while (!end_section(lines[line]))
                                puts(lines[line++]);
                } else if (streq(type, "example")) {
-                       line = find_section(lines, type);
+                       line = find_section(lines, type, false);
                        if (lines[line]) {
                                unsigned int strip;
                                line++;
@@ -149,16 +215,18 @@ int main(int argc, char *argv[])
                                        line++;
                                }
                        }
+               } else if (streq(type, "functions")) {
+                       while (lines[line = find_summary(lines, NULL)]) {
+                               const char *dash = strstr(lines[line], " - ");
+                               printf("%.*s\n",
+                                      dash - lines[line], lines[line]);
+                               lines += line+1;
+                       }
                } else if (streq(type, "all")) {
                        for (line = 0; lines[line]; line++)
                                puts(lines[line]);
                } else
                        errx(1, "Unknown type '%s'", type);
-                       
-               talloc_free(lines);
        }
        return 0;
 }
-
-               
-