Package: guile;
Reported by: Tkprom <tk.code <at> protonmail.com>
Date: Sat, 3 Feb 2018 17:31:02 UTC
Severity: normal
Tags: patch
View this message in rfc822 format
From: Tkprom <tk.code <at> protonmail.com> To: 30338 <at> debbugs.gnu.org Subject: bug#30338: [PATCH] Fix up doc-snarfing in doc-snarf.scm Date: Sat, 03 Feb 2018 03:34:57 -0500
[Message part 1 (text/plain, inline)]
Hi,
I only found out about guild doc-snarf after I produced most of my source documentation using internal doc-strings (string after `(define'). However,
doc-snarf only works with ;; doc-strings or a combination of ;; and internal doc-strings, never on internal doc-strings alone.
I have now made some changes to doc-snarf.scm to make it work with stand-alone internal doc-strings.
========= output of git format-patch =========
Command doc-snarf of guild now works for internal doc-strings just
like for `;;' doc-strings.
* module/scripts/doc-snarf (snarf):
- defined `int-doc-entry' to produce a correct entry from an internal
doc-string and cons it to the list of entries
- added `signature-start' detection to the top-level doc detection
`let'
- int-doc-entry messes up line numbers; add calls to ftell and seek to
sort this out (overkill and too expensive?)
---
module/scripts/doc-snarf.scm | 53 +++++++++++++++++++++++++++++++++++++-------
1 file changed, 45 insertions(+), 8 deletions(-)
diff --git a/module/scripts/doc-snarf.scm b/module/scripts/doc-snarf.scm
index fa3dfb312..5b709b110 100644
--- a/module/scripts/doc-snarf.scm
+++ b/module/scripts/doc-snarf.scm
@@ -191,7 +191,7 @@ return the standard internal docstring if found. Return #f if not."
(eq? 'define (car form))
(pair? (cadr form))
(symbol? (caadr form))
- (string? (caddr form)))
+ (string? (caddr form)))
(caddr form))
((and (list? form) ; (define VAR (lambda ARGS "DOC" ...))
(< 2 (length form))
@@ -204,6 +204,7 @@ return the standard internal docstring if found. Return #f if not."
(caddr (caddr form)))
(else #f))))
+
;; Split @var{string} into lines, adding @var{prefix} to each.
;;-ttn-mod: new proc
(define (split-prefixed string prefix)
@@ -220,6 +221,7 @@ return the standard internal docstring if found. Return #f if not."
;;-Author: Martin Grabmueller <mgrabmue <at> cs.tu-berlin.de>
;;-Created: 2001-02-17
;;-ttn-mod: regluarize lang parm lookup, add "std int doc" snarfing (2 places)
+;;-tk-mod: add standalone "std int doc" snarfing and fix source code lines
(define (snarf input-file lang)
(let* ((i-p (open-input-file input-file))
(parm-regexp (lambda (parm) (make-regexp (lang-parm lang parm))))
@@ -228,6 +230,7 @@ return the standard internal docstring if found. Return #f if not."
(docstring-prefix (parm-regexp 'docstring-prefix))
(option-prefix (parm-regexp 'option-prefix))
(signature-start (parm-regexp 'signature-start))
+ (std-int-doc? (lang-parm lang 'std-int-doc?))
(augmented-options
(lambda (line i-p options)
(let ((int-doc (and (lang-parm lang 'std-int-doc?)
@@ -235,7 +238,17 @@ return the standard internal docstring if found. Return #f if not."
(and d (split-prefixed d "internal: "))))))
(if int-doc
(append (reverse int-doc) options)
- options)))))
+ options))))
+ (int-doc-entry (lambda (line entries str-line i-p)
+ (let*
+ ((thing (find-std-int-doc line i-p)))
+ (if thing
+ (cons (parse-entry (list thing)
+ '()
+ line
+ (port-filename i-p)
+ str-line) entries)
+ entries)))))
(let lp ((line (read-line i-p)) (state 'neutral) (doc-strings '())
(options '()) (entries '()) (lno 0))
@@ -245,13 +258,37 @@ return the standard internal docstring if found. Return #f if not."
(reverse entries))
;; State 'neutral: we're currently not within a docstring or
- ;; option section
+ ;; option section, or at a signature (in case of languages that
+ ;; have internal doc strings).
((eq? state 'neutral)
- (let ((m (regexp-exec docstring-start line)))
- (if m
- (lp (read-line i-p) 'doc-string
- (list (match:substring m 1)) '() entries (+ lno 1))
- (lp (read-line i-p) state '() '() entries (+ lno 1)))))
+ (let ((m0 (regexp-exec docstring-start line))
+ (m1 (regexp-exec signature-start line)))
+
+ (cond
+ (m0
+ (lp (read-line i-p) 'doc-string
+ (list (match:substring m0 1)) '() entries (+ lno 1)))
+
+ ((and std-int-doc? m1) ;Add int-doc string to entries (tk-mod).
+ (let
+ ((where (ftell i-p)) ;Proc int-doc-entry is going to
+ ;mess up line counting, so
+ ;record where we are in the
+ ;world.
+ (entries (int-doc-entry
+ line
+ entries
+ (+ 2 lno)
+ i-p)))
+ (seek i-p where SEEK_SET) ;Rewind (is this too expensive?)
+ (lp (read-line i-p)
+ 'neutral
+ '()
+ '()
+ entries
+ (+ 1 lno))))
+ (#t
+ (lp (read-line i-p) state '() '() entries (+ lno 1))))))
;; State 'doc-string: we have started reading a docstring and
;; are waiting for more, for options or for a define.
--
2.15.1
Todor Kondić
Sent with [ProtonMail](https://protonmail.com) Secure Email.
[Message part 2 (text/html, inline)]
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.