1 /* Generate doc-string file for GNU Emacs from source files.
2 Copyright (C) 1985, 1986, 1992, 1993, 1994, 1997, 1999, 2000, 2001,
3 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
4 Free Software Foundation, Inc.
6 This file is part of GNU Emacs.
8 GNU Emacs is free software: you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation, either version 3 of the License, or
11 (at your option) any later version.
13 GNU Emacs is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License
19 along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. */
22 /* The arguments given to this program are all the C and Lisp source files
23 of GNU Emacs. .elc and .el and .c files are allowed.
24 A .o file can also be specified; the .c file it was made from is used.
25 This helps the makefile pass the correct list of files.
26 Option -d DIR means change to DIR before looking for files.
28 The results, which go to standard output or to a file
29 specified with -a or -o (-a to append, -o to start from nothing),
30 are entries containing function or variable names and their documentation.
31 Each entry starts with a ^_ character.
32 Then comes F for a function or V for a variable.
33 Then comes the function or variable name, terminated with a newline.
34 Then comes the documentation for that function or variable.
39 /* defined to be emacs_main, sys_fopen, etc. in config.h */
52 #endif /* WINDOWSNT */
55 #define READ_TEXT "rt"
56 #define READ_BINARY "rb"
57 #else /* not DOS_NT */
59 #define READ_BINARY "r"
60 #endif /* not DOS_NT */
63 #define DIRECTORY_SEP '/'
66 #ifndef IS_DIRECTORY_SEP
67 #define IS_DIRECTORY_SEP(_c_) ((_c_) == DIRECTORY_SEP)
70 int scan_file (char *filename
);
71 int scan_lisp_file (const char *filename
, const char *mode
);
72 int scan_c_file (char *filename
, const char *mode
);
73 void fatal (const char *s1
, const char *s2
) NO_RETURN
;
76 /* s/msdos.h defines this as sys_chdir, but we're not linking with the
77 file where that function is defined. */
83 /* Stdio stream for output to the DOC file. */
86 /* Name this program was invoked with. */
89 /* Print error message. `s1' is printf control string, `s2' is arg for it. */
93 error (const char *s1
, const char *s2
)
95 fprintf (stderr
, "%s: ", progname
);
96 fprintf (stderr
, s1
, s2
);
97 fprintf (stderr
, "\n");
100 /* Print error message and exit. */
104 fatal (const char *s1
, const char *s2
)
110 /* Like malloc but get fatal error if memory is exhausted. */
113 xmalloc (unsigned int size
)
115 void *result
= (void *) malloc (size
);
117 fatal ("virtual memory exhausted", 0);
122 main (int argc
, char **argv
)
132 /* Don't put CRs in the DOC file. */
135 #if 0 /* Suspicion is that this causes hanging.
136 So instead we require people to use -o on MSDOS. */
137 (stdout
)->_flag
&= ~_IOTEXT
;
138 _setmode (fileno (stdout
), O_BINARY
);
144 _setmode (fileno (stdout
), O_BINARY
);
145 #endif /* WINDOWSNT */
147 /* If first two args are -o FILE, output to FILE. */
149 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-o"))
151 outfile
= fopen (argv
[i
+ 1], "w");
154 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-a"))
156 outfile
= fopen (argv
[i
+ 1], "a");
159 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-d"))
161 if (chdir (argv
[i
+ 1]) != 0)
163 perror (argv
[i
+ 1]);
170 fatal ("No output file specified", "");
173 for (; i
< argc
; i
++)
176 /* Don't process one file twice. */
177 for (j
= first_infile
; j
< i
; j
++)
178 if (! strcmp (argv
[i
], argv
[j
]))
181 err_count
+= scan_file (argv
[i
]);
183 return (err_count
> 0 ? EXIT_FAILURE
: EXIT_SUCCESS
);
186 /* Add a source file name boundary marker in the output file. */
188 put_filename (char *filename
)
192 for (tmp
= filename
; *tmp
; tmp
++)
194 if (IS_DIRECTORY_SEP(*tmp
))
200 fprintf (outfile
, "%s\n", filename
);
203 /* Read file FILENAME and output its doc strings to outfile. */
204 /* Return 1 if file is not found, 0 if it is found. */
207 scan_file (char *filename
)
210 size_t len
= strlen (filename
);
212 put_filename (filename
);
213 if (len
> 4 && !strcmp (filename
+ len
- 4, ".elc"))
214 return scan_lisp_file (filename
, READ_BINARY
);
215 else if (len
> 3 && !strcmp (filename
+ len
- 3, ".el"))
216 return scan_lisp_file (filename
, READ_TEXT
);
218 return scan_c_file (filename
, READ_TEXT
);
223 /* Some state during the execution of `read_c_string_or_comment'. */
226 /* A count of spaces and newlines that have been read, but not output. */
227 unsigned pending_spaces
, pending_newlines
;
229 /* Where we're reading from. */
232 /* If non-zero, a buffer into which to copy characters. */
234 /* If non-zero, a file into which to copy characters. */
237 /* A keyword we look for at the beginning of lines. If found, it is
238 not copied, and SAW_KEYWORD is set to true. */
240 /* The current point we've reached in an occurrence of KEYWORD in
242 const char *cur_keyword_ptr
;
243 /* Set to true if we saw an occurrence of KEYWORD. */
247 /* Output CH to the file or buffer in STATE. Any pending newlines or
248 spaces are output first. */
251 put_char (int ch
, struct rcsoc_state
*state
)
256 if (state
->pending_newlines
> 0)
258 state
->pending_newlines
--;
261 else if (state
->pending_spaces
> 0)
263 state
->pending_spaces
--;
270 putc (out_ch
, state
->out_file
);
272 *state
->buf_ptr
++ = out_ch
;
274 while (out_ch
!= ch
);
277 /* If in the middle of scanning a keyword, continue scanning with
278 character CH, otherwise output CH to the file or buffer in STATE.
279 Any pending newlines or spaces are output first, as well as any
280 previously scanned characters that were thought to be part of a
281 keyword, but were in fact not. */
284 scan_keyword_or_put_char (int ch
, struct rcsoc_state
*state
)
287 && *state
->cur_keyword_ptr
== ch
288 && (state
->cur_keyword_ptr
> state
->keyword
289 || state
->pending_newlines
> 0))
290 /* We might be looking at STATE->keyword at some point.
291 Keep looking until we know for sure. */
293 if (*++state
->cur_keyword_ptr
== '\0')
294 /* Saw the whole keyword. Set SAW_KEYWORD flag to true. */
296 state
->saw_keyword
= 1;
298 /* Reset the scanning pointer. */
299 state
->cur_keyword_ptr
= state
->keyword
;
301 /* Canonicalize whitespace preceding a usage string. */
302 state
->pending_newlines
= 2;
303 state
->pending_spaces
= 0;
305 /* Skip any whitespace between the keyword and the
308 ch
= getc (state
->in_file
);
309 while (ch
== ' ' || ch
== '\n');
311 /* Output the open-paren we just read. */
312 put_char (ch
, state
);
314 /* Skip the function name and replace it with `fn'. */
316 ch
= getc (state
->in_file
);
317 while (ch
!= ' ' && ch
!= ')');
318 put_char ('f', state
);
319 put_char ('n', state
);
321 /* Put back the last character. */
322 ungetc (ch
, state
->in_file
);
327 if (state
->keyword
&& state
->cur_keyword_ptr
> state
->keyword
)
328 /* We scanned the beginning of a potential usage
329 keyword, but it was a false alarm. Output the
334 for (p
= state
->keyword
; p
< state
->cur_keyword_ptr
; p
++)
335 put_char (*p
, state
);
337 state
->cur_keyword_ptr
= state
->keyword
;
340 put_char (ch
, state
);
345 /* Skip a C string or C-style comment from INFILE, and return the
346 character that follows. COMMENT non-zero means skip a comment. If
347 PRINTFLAG is positive, output string contents to outfile. If it is
348 negative, store contents in buf. Convert escape sequences \n and
349 \t to newline and tab; discard \ followed by newline.
350 If SAW_USAGE is non-zero, then any occurrences of the string `usage:'
351 at the beginning of a line will be removed, and *SAW_USAGE set to
352 true if any were encountered. */
355 read_c_string_or_comment (FILE *infile
, int printflag
, int comment
, int *saw_usage
)
358 struct rcsoc_state state
;
360 state
.in_file
= infile
;
361 state
.buf_ptr
= (printflag
< 0 ? buf
: 0);
362 state
.out_file
= (printflag
> 0 ? outfile
: 0);
363 state
.pending_spaces
= 0;
364 state
.pending_newlines
= 0;
365 state
.keyword
= (saw_usage
? "usage:" : 0);
366 state
.cur_keyword_ptr
= state
.keyword
;
367 state
.saw_keyword
= 0;
371 while (c
== '\n' || c
== '\r' || c
== '\t' || c
== ' ')
376 while (c
!= EOF
&& (comment
? c
!= '*' : c
!= '"'))
381 if (c
== '\n' || c
== '\r')
393 state
.pending_spaces
++;
396 state
.pending_newlines
++;
397 state
.pending_spaces
= 0;
400 scan_keyword_or_put_char (c
, &state
);
416 scan_keyword_or_put_char ('*', &state
);
423 /* If we had a "", concatenate the two strings. */
432 *saw_usage
= state
.saw_keyword
;
439 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
440 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
443 write_c_args (FILE *out
, char *func
, char *buf
, int minargs
, int maxargs
)
448 size_t ident_length
= 0;
450 fprintf (out
, "(fn");
455 for (p
= buf
; *p
; p
++)
459 /* Notice when a new identifier starts. */
460 if ((('A' <= c
&& c
<= 'Z')
461 || ('a' <= c
&& c
<= 'z')
462 || ('0' <= c
&& c
<= '9')
474 ident_length
= p
- ident_start
;
478 /* Found the end of an argument, write out the last seen
480 if (c
== ',' || c
== ')')
482 if (ident_length
== 0)
484 error ("empty arg list for `%s' should be (void), not ()", func
);
488 if (strncmp (ident_start
, "void", ident_length
) == 0)
493 if (minargs
== 0 && maxargs
> 0)
494 fprintf (out
, "&optional ");
499 /* In C code, `default' is a reserved word, so we spell it
500 `defalt'; unmangle that here. */
501 if (ident_length
== 6 && strncmp (ident_start
, "defalt", 6) == 0)
502 fprintf (out
, "DEFAULT");
504 while (ident_length
-- > 0)
507 if (c
>= 'a' && c
<= 'z')
508 /* Upcase the letter. */
511 /* Print underscore as hyphen. */
521 /* Read through a c file. If a .o file is named,
522 the corresponding .c or .m file is read instead.
523 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
524 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
527 scan_c_file (char *filename
, const char *mode
)
532 register int defunflag
;
533 register int defvarperbufferflag
;
534 register int defvarflag
;
535 int minargs
, maxargs
;
536 int extension
= filename
[strlen (filename
) - 1];
538 if (extension
== 'o')
539 filename
[strlen (filename
) - 1] = 'c';
541 infile
= fopen (filename
, mode
);
543 if (infile
== NULL
&& extension
== 'o')
546 filename
[strlen (filename
) - 1] = 'm';
547 infile
= fopen (filename
, mode
);
549 filename
[strlen (filename
) - 1] = 'c'; /* don't confuse people */
552 /* No error if non-ex input file */
559 /* Reset extension to be able to detect duplicate files. */
560 filename
[strlen (filename
) - 1] = extension
;
563 while (!feof (infile
))
567 if (c
!= '\n' && c
!= '\r')
602 defvarperbufferflag
= (c
== 'P');
615 defunflag
= c
== 'U';
617 defvarperbufferflag
= 0;
628 /* Lisp variable or function name. */
632 c
= read_c_string_or_comment (infile
, -1, 0, 0);
634 /* DEFVAR_LISP ("name", addr, "doc")
635 DEFVAR_LISP ("name", addr /\* doc *\/)
636 DEFVAR_LISP ("name", addr, doc: /\* doc *\/) */
640 else if (defvarperbufferflag
)
644 else /* For DEFSIMPLE and DEFPRED */
653 if (defunflag
&& (commas
== 1 || commas
== 2))
658 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t');
662 if (commas
== 2) /* pick up minargs */
663 scanned
= fscanf (infile
, "%d", &minargs
);
664 else /* pick up maxargs */
665 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
668 scanned
= fscanf (infile
, "%d", &maxargs
);
679 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
683 c
= read_c_string_or_comment (infile
, 0, 0, 0);
685 while (c
!= EOF
&& c
!= ',' && c
!= '/')
690 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
692 while ((c
>= 'a' && c
<= 'z') || (c
>= 'Z' && c
<= 'Z'))
698 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
705 && (c
= getc (infile
),
709 int comment
= c
!= '"';
713 putc (defvarflag
? 'V' : 'F', outfile
);
714 fprintf (outfile
, "%s\n", buf
);
717 getc (infile
); /* Skip past `*' */
718 c
= read_c_string_or_comment (infile
, 1, comment
, &saw_usage
);
720 /* If this is a defun, find the arguments and print them. If
721 this function takes MANY or UNEVALLED args, then the C source
722 won't give the names of the arguments, so we shouldn't bother
725 Various doc-string styles:
726 0: DEFUN (..., "DOC") (args) [!comment]
727 1: DEFUN (..., /\* DOC *\/ (args)) [comment && !doc_keyword]
728 2: DEFUN (..., doc: /\* DOC *\/) (args) [comment && doc_keyword]
730 if (defunflag
&& maxargs
!= -1 && !saw_usage
)
732 char argbuf
[1024], *p
= argbuf
;
734 if (!comment
|| doc_keyword
)
742 /* Skip into arguments. */
749 /* Copy arguments into ARGBUF. */
752 *p
++ = c
= getc (infile
);
756 fprintf (outfile
, "\n\n");
757 write_c_args (outfile
, buf
, argbuf
, minargs
, maxargs
);
759 else if (defunflag
&& maxargs
== -1 && !saw_usage
)
760 /* The DOC should provide the usage form. */
761 fprintf (stderr
, "Missing `usage' for function `%s'.\n", buf
);
769 /* Read a file of Lisp code, compiled or interpreted.
771 (defun NAME ARGS DOCSTRING ...)
772 (defmacro NAME ARGS DOCSTRING ...)
773 (defsubst NAME ARGS DOCSTRING ...)
774 (autoload (quote NAME) FILE DOCSTRING ...)
775 (defvar NAME VALUE DOCSTRING)
776 (defconst NAME VALUE DOCSTRING)
777 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
778 (fset (quote NAME) #[... DOCSTRING ...])
779 (defalias (quote NAME) #[... DOCSTRING ...])
780 (custom-declare-variable (quote NAME) VALUE DOCSTRING ...)
781 starting in column zero.
782 (quote NAME) may appear as 'NAME as well.
784 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
785 When we find that, we save it for the following defining-form,
786 and we use that instead of reading a doc string within that defining-form.
788 For defvar, defconst, and fset we skip to the docstring with a kludgy
789 formatting convention: all docstrings must appear on the same line as the
790 initial open-paren (the one in column zero) and must contain a backslash
791 and a newline immediately after the initial double-quote. No newlines
792 must appear between the beginning of the form and the first double-quote.
793 For defun, defmacro, and autoload, we know how to skip over the
794 arglist, but the doc string must still have a backslash and newline
795 immediately after the double quote.
796 The only source files that must follow this convention are preloaded
797 uncompiled ones like loaddefs.el and bindings.el; aside
798 from that, it is always the .elc file that we look at, and they are no
799 problem because byte-compiler output follows this convention.
800 The NAME and DOCSTRING are output.
801 NAME is preceded by `F' for a function or `V' for a variable.
802 An entry is output only if DOCSTRING has \ newline just after the opening "
806 skip_white (FILE *infile
)
809 while (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r')
815 read_lisp_symbol (FILE *infile
, char *buffer
)
818 char *fillp
= buffer
;
825 *(++fillp
) = getc (infile
);
826 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r' || c
== '(' || c
== ')')
837 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
843 scan_lisp_file (const char *filename
, const char *mode
)
847 char *saved_string
= 0;
849 infile
= fopen (filename
, mode
);
853 return 0; /* No error */
857 while (!feof (infile
))
862 /* If not at end of line, skip till we get to one. */
863 if (c
!= '\n' && c
!= '\r')
868 /* Skip the line break. */
869 while (c
== '\n' || c
== '\r')
871 /* Detect a dynamic doc string and save it for the next expression. */
880 /* Read the length. */
881 while ((c
= getc (infile
),
882 c
>= '0' && c
<= '9'))
888 /* The next character is a space that is counted in the length
889 but not part of the doc string.
890 We already read it, so just ignore it. */
893 /* Read in the contents. */
895 saved_string
= (char *) xmalloc (length
);
896 for (i
= 0; i
< length
; i
++)
897 saved_string
[i
] = getc (infile
);
898 /* The last character is a ^_.
899 That is needed in the .elc file
900 but it is redundant in DOC. So get rid of it here. */
901 saved_string
[length
- 1] = 0;
902 /* Skip the line break. */
903 while (c
== '\n' && c
== '\r')
905 /* Skip the following line. */
906 while (c
!= '\n' && c
!= '\r')
915 read_lisp_symbol (infile
, buffer
);
917 if (! strcmp (buffer
, "defun")
918 || ! strcmp (buffer
, "defmacro")
919 || ! strcmp (buffer
, "defsubst"))
922 read_lisp_symbol (infile
, buffer
);
924 /* Skip the arguments: either "nil" or a list in parens */
927 if (c
== 'n') /* nil */
929 if ((c
= getc (infile
)) != 'i'
930 || (c
= getc (infile
)) != 'l')
932 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
939 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
948 /* If the next three characters aren't `dquote bslash newline'
949 then we're not reading a docstring.
951 if ((c
= getc (infile
)) != '"'
952 || (c
= getc (infile
)) != '\\'
953 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
956 fprintf (stderr
, "## non-docstring in %s (%s)\n",
963 else if (! strcmp (buffer
, "defvar")
964 || ! strcmp (buffer
, "defconst"))
968 read_lisp_symbol (infile
, buffer
);
970 if (saved_string
== 0)
973 /* Skip until the end of line; remember two previous chars. */
974 while (c
!= '\n' && c
!= '\r' && c
>= 0)
981 /* If two previous characters were " and \,
982 this is a doc string. Otherwise, there is none. */
983 if (c2
!= '"' || c1
!= '\\')
986 fprintf (stderr
, "## non-docstring in %s (%s)\n",
994 else if (! strcmp (buffer
, "custom-declare-variable")
995 || ! strcmp (buffer
, "defvaralias")
1003 read_lisp_symbol (infile
, buffer
);
1009 "## unparsable name in custom-declare-variable in %s\n",
1013 read_lisp_symbol (infile
, buffer
);
1014 if (strcmp (buffer
, "quote"))
1017 "## unparsable name in custom-declare-variable in %s\n",
1021 read_lisp_symbol (infile
, buffer
);
1026 "## unparsable quoted name in custom-declare-variable in %s\n",
1032 if (saved_string
== 0)
1034 /* Skip to end of line; remember the two previous chars. */
1035 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1042 /* If two previous characters were " and \,
1043 this is a doc string. Otherwise, there is none. */
1044 if (c2
!= '"' || c1
!= '\\')
1047 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1055 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
1057 char c1
= 0, c2
= 0;
1062 read_lisp_symbol (infile
, buffer
);
1067 fprintf (stderr
, "## unparsable name in fset in %s\n",
1071 read_lisp_symbol (infile
, buffer
);
1072 if (strcmp (buffer
, "quote"))
1074 fprintf (stderr
, "## unparsable name in fset in %s\n",
1078 read_lisp_symbol (infile
, buffer
);
1083 "## unparsable quoted name in fset in %s\n",
1089 if (saved_string
== 0)
1091 /* Skip to end of line; remember the two previous chars. */
1092 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1099 /* If two previous characters were " and \,
1100 this is a doc string. Otherwise, there is none. */
1101 if (c2
!= '"' || c1
!= '\\')
1104 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1112 else if (! strcmp (buffer
, "autoload"))
1117 read_lisp_symbol (infile
, buffer
);
1122 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1126 read_lisp_symbol (infile
, buffer
);
1127 if (strcmp (buffer
, "quote"))
1129 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1133 read_lisp_symbol (infile
, buffer
);
1138 "## unparsable quoted name in autoload in %s\n",
1143 skip_white (infile
);
1144 if ((c
= getc (infile
)) != '\"')
1146 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
1150 read_c_string_or_comment (infile
, 0, 0, 0);
1151 skip_white (infile
);
1153 if (saved_string
== 0)
1155 /* If the next three characters aren't `dquote bslash newline'
1156 then we're not reading a docstring. */
1157 if ((c
= getc (infile
)) != '"'
1158 || (c
= getc (infile
)) != '\\'
1159 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
1162 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1171 else if (! strcmp (buffer
, "if")
1172 || ! strcmp (buffer
, "byte-code"))
1179 fprintf (stderr
, "## unrecognized top-level form, %s (%s)\n",
1185 /* At this point, we should either use the previous
1186 dynamic doc string in saved_string
1187 or gobble a doc string from the input file.
1189 In the latter case, the opening quote (and leading
1190 backslash-newline) have already been read. */
1192 putc (037, outfile
);
1193 putc (type
, outfile
);
1194 fprintf (outfile
, "%s\n", buffer
);
1197 fputs (saved_string
, outfile
);
1198 /* Don't use one dynamic doc string twice. */
1199 free (saved_string
);
1203 read_c_string_or_comment (infile
, 1, 0, 0);
1210 /* make-docfile.c ends here */