Debian Codegraph @

guile/modules/system/documentation/output.scm

raw
1 ;;; output.scm -- Output documentation "snarffed" from C files in Texi/GDF.
2 ;;;
3 ;;; Copyright 2006-2025 Free Software Foundation, Inc.
4 ;;;
5 ;;; This file is part of Guile-GnuTLS.
6 ;;;
7 ;;; This program is free software: you can redistribute it and/or modify
8 ;;; it under the terms of the GNU General Public License as published by
9 ;;; the Free Software Foundation, either version 3 of the License, or
10 ;;; (at your option) any later version.
11 ;;;
12 ;;; This program is distributed in the hope that it will be useful,
13 ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
14 ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 ;;; GNU General Public License for more details.
16 ;;;
17 ;;; You should have received a copy of the GNU General Public License
18 ;;; along with this program. If not, see <https://www.gnu.org/licenses/>.
19
20 (define-module (system documentation output)
21 :use-module (srfi srfi-1)
22 :use-module (srfi srfi-13)
23 :use-module (srfi srfi-39)
24 :autoload (system documentation c-snarf) (run-cpp-and-extract-snarfing)
25
26 :export (schemify-name
27 scheme-procedure-texi-line
28 procedure-gdf-string
29 procedure-texi-documentation
30 output-procedure-texi-documentation-from-c-file
31 *document-c-functions?*))
32
33 ;;; Author: Ludovic Courtès
34 ;;;
35 ;;; Commentary:
36 ;;;
37 ;;; This module provides support function to issue Texinfo or GDF (Guile
38 ;;; Documentation Format) documentation from "snarffed" C files.
39 ;;;
40 ;;; Code:
41
42
43 ;;;
44 ;;; Utility.
45 ;;;
46
47 (define (schemify-name str)
48 "Turn @var{str}, a C variable or function name, into a more ``Schemey''
49 form, e.g., one with dashed instead of underscores, etc."
50 (string-map (lambda (chr)
51 (if (eq? chr #\_)
52 #\-
53 chr))
54 (if (string-suffix? "_p" str)
55 (string-append (substring str 0
56 (- (string-length str) 2))
57 "?")
58 str)))
59
60
61 ;;;
62 ;;; Issuing Texinfo and GDF-formatted doc (i.e., `guile-procedures.texi').
63 ;;; GDF = Guile Documentation Format
64 ;;;
65
66 (define *document-c-functions?*
67 ;; Whether to mention C function names along with Scheme procedure names.
68 (make-parameter #t))
69
70 (define (scheme-procedure-texi-line proc-name args
71 required-args optional-args
72 rest-arg?)
73 "Return a Texinfo string describing the Scheme procedure named
74 @var{proc-name}, whose arguments are listed in @var{args} (a list of strings)
75 and whose signature is defined by @var{required-args}, @var{optional-args}
76 and @var{rest-arg?}."
77 (string-append "@deffn {Scheme Procedure} " proc-name " "
78 (string-join (take args required-args) " ")
79 (string-join (take (drop args required-args)
80 (+ optional-args
81 (if rest-arg? 1 0)))
82 " [" 'prefix)
83 (if rest-arg? "...]" "")
84 (make-string optional-args #\])))
85
86 (define (procedure-gdf-string proc-doc)
87 "Issue a Texinfo/GDF docstring corresponding to @var{proc-doc}, a
88 documentation alist as returned by @code{parse-snarfed-line}. To produce
89 actual GDF-formatted doc, the resulting string must be processed by
90 @code{makeinfo}."
91 (let* ((proc-name (assq-ref proc-doc 'scheme-name))
92 (args (assq-ref proc-doc 'arguments))
93 (signature (assq-ref proc-doc 'signature))
94 (required-args (assq-ref signature 'required))
95 (optional-args (assq-ref signature 'optional))
96 (rest-arg? (assq-ref signature 'rest?))
97 (location (assq-ref proc-doc 'location))
98 (file-name (car location))
99 (line (cadr location))
100 (documentation (assq-ref proc-doc 'documentation)))
101 (string-append " " ;; form feed
102 proc-name (string #\newline)
103 (format #f "@c snarfed from ~a:~a~%"
104 file-name line)
105
106 (scheme-procedure-texi-line proc-name
107 (map schemify-name args)
108 required-args optional-args
109 rest-arg?)
110
111 (string #\newline)
112 documentation (string #\newline)
113 "@end deffn" (string #\newline))))
114
115 (define (procedure-texi-documentation proc-doc)
116 "Issue a Texinfo docstring corresponding to @var{proc-doc}, a documentation
117 alist as returned by @var{parse-snarfed-line}. The resulting Texinfo string
118 is meant for use in a manual since it also documents the corresponding C
119 function."
120 (let* ((proc-name (assq-ref proc-doc 'scheme-name))
121 (c-name (assq-ref proc-doc 'c-name))
122 (args (assq-ref proc-doc 'arguments))
123 (signature (assq-ref proc-doc 'signature))
124 (required-args (assq-ref signature 'required))
125 (optional-args (assq-ref signature 'optional))
126 (rest-arg? (assq-ref signature 'rest?))
127 (location (assq-ref proc-doc 'location))
128 (file-name (car location))
129 (line (cadr location))
130 (documentation (assq-ref proc-doc 'documentation)))
131 (string-append (string #\newline)
132 (format #f "@c snarfed from ~a:~a~%"
133 file-name line)
134
135 ;; document the Scheme procedure
136 (scheme-procedure-texi-line proc-name
137 (map schemify-name args)
138 required-args optional-args
139 rest-arg?)
140 (string #\newline)
141
142 (if (*document-c-functions?*)
143 (string-append
144 ;; document the C function
145 "@deffnx {C Function} " c-name " ("
146 (if (null? args)
147 "void"
148 (string-join (map (lambda (arg)
149 (string-append "SCM " arg))
150 args)
151 ", "))
152 ")" (string #\newline))
153 "")
154
155 documentation (string #\newline)
156 "@end deffn" (string #\newline))))
157
158
159 ;;;
160 ;;; Very high-level interface.
161 ;;;
162
163 (define (output-procedure-texi-documentation-from-c-file c-file cpp cflags
164 port)
165 (for-each (lambda (texi-string)
166 (display texi-string port))
167 (map procedure-texi-documentation
168 (run-cpp-and-extract-snarfing c-file cpp cflags))))
169
170
171 ;;; output.scm ends here
172
173 ;;; Local Variables:
174 ;;; mode: scheme
175 ;;; coding: utf-8
176 ;;; End:
177
178 ;;; arch-tag: 20ca493a-6f1a-4d7f-9d24-ccce0d32df49