Re: Scheme file docstring format

[Keisuke Nishida]

At 16 Feb 2001 18:45:37 +0000,
Neil Jerram wrote:
> 
> OK, I'd like to propose a format for Scheme file docstrings, and also
> the rule for how the snarfer finds these docstrings.

I'd like to propose to add sectioning meta info in addition to
docstrings.  For example, the following is part of my VM code:

------------------------------------------------------------------------
;;;
;;; Package
;;;

(define-class <package> (<vmodule>)
  (table (make-hash-table 11)))

;; simple package

(define-class <simple-package> (<package>) directory)

(define (make-simple-package dir)
  (make <simple-package> :directory dir))

;; custom package

(define-class <custom-package> (<package>)
  directory name category version author modules)

(define (make-custom-package dir)
  (call-with-input-file (expand-file-name *package-def* dir)
    (lambda (p)
      (apply make <custom-package> :directory dir :name (cdr (read p))))))

;; multi package

(define-class <multi-package> (<package>) modules)

(define (make-multi-package dirs)
  (make <multi-package>
        :modules (filter identity (map try-load-package dirs))))
------------------------------------------------------------------------

I could rewrite this as follows with docstrings and sections:

------------------------------------------------------------------------
;;@section Packages
;;
;; Packages are special modules that associate names with modules or
;; other packages in terms of file names.

;;@ <package> (<vmodule>)
;;
;; A class that ...
;;
(define-class <package> (<vmodule>)
  (table (make-hash-table 11)))

;;@subsection Simple Packages
;; 
;; Simple packages are ...

;;@ <simple-package> (<package>)
;; 
(define-class <simple-package> (<package>) directory)

;;@ make-simple-package dir
;; 
(define (make-simple-package dir)
  (make <simple-package> :directory dir))
...
------------------------------------------------------------------------

The benefit is that we can easily produce a quick reference manual
organized in sections.  Also, this style of source code might be more
readable than plain code if one highlighted sections and moved around
it in outline-minor-mode.

> First the format:
> 
> - Following the elisp coding standards, Scheme file docstrings begin
>   with two semicolons, aligned with the following `(define ...)'.
(snip)
> - Having found an appropriate define expression, the snarfer searches
>   backwards until it finds a line that does not begin with exactly two
>   semicolons.  The region that it traverses in doing this is the
>   docstring.
> 
> - If the first word of the first line of the docstring matches the
>   name being documented, it is taken as the PROTOTYPE line and not
>   included in the DOCTEXT.  Otherwise the first line is included in
>   the DOCTEXT, and a prototype line is constructed from the define
>   expression.

I think the following simple format/rule is sufficient:

- Docstrings begin with a line ";;@ NAME [PARAMETER...]"
- Docstrings end with a non-comment line

`define' is not the only definition syntax we use.  We have
define-macro, define-class, etc., and I have define-language,
define-package, and define-command in my VM.  In order to make
things simple, I think the cost of adding one line is not
significant.  We can easily edit/update docstrings by adding
appropriate Emacs commands.

In order to avoid name inconsistency, adding some heuristics,
like comparing NAME and '(define ...)', would be fine.  But
I think it should be an extra effort.  But maybe I'm wrong.

Kei