scm2wiki is an in-source documentation tool for Chicken Scheme. It generates documentation from comments in a Scheme source file. scm2wiki renders documentation as Github flavored Markdown, as well as Chicken's custom svnwiki format.

• Features
• Usage
  • Installation
  • Command Line Usage
  • Example
• Alternatives to scm2wiki
• Version History
• TODO
• Contributing

scm2wiki uses stand-alone comment blocks and commented definitions in Scheme source code to generate documentation in Markdown or svnwiki format. scm2wiki supports Markdown in comments.

scm2wiki can generate documentation for the following definition types:

• variable and procedure definitions using define
• constant definitions using define-constant
• macro definitions using define-syntax (limited support, see example)
• record type definitions using define-record, define-record-type, and defstruct
• coops class definitions using define-class
• coops generic procedure specializations using define-method

scm2wiki understands Chicken Scheme's native module declarations. By default, it will only generate documentation for symbols that are exported.

There is also some limited support for simple type annotations, including typed records. However, this feature is not yet complete.

For svnwiki output, scm2wiki translates Markdown text. However, translation is limited and does not yet support lists, plain hyperlinks, inline images, and formatting in tables.

scm2wiki is available from the official Chicken Egg repository. To install it, simply run

$ chicken-install scm2wiki

$ scm2wiki [options...]

By default, scm2wiki reads from STDIN and outputs Markdown to STDOUT. The following options are available:

scm2wiki will only consider code comments with a specific, user-defined prefix. By default, the prefix is ";;;". See the following example for a complete list of supported source code elements.

If the -a flag is specified, anchor links will be created for each defined binding. This allows for easy cross-referencing of definitions. The anchor id is the name of the binding, prefixed by def-. Characters not allowed in URLs are stripped. This feature works only in Markdown mode.

;; this comment will be ignored

;;; # A Test Heading

(module foo
    *

  (import scheme (chicken base) srfi-9 coops defstruct)

  ;;; A stand-alone comment stretching multiple lines
  ;;; *with* `formatting` **and** a [named link](https://call-cc.org)

  ;;; ```Scheme
  ;;; ;; A fenced code block
  ;;; (+ 1 2 3)
  ;;; ```

  ;;; an   | interesting | table
  ;;; ---- | ----------- | -----
  ;;; with | actual      | content

  ;; An undocumented variable definition
  (define bar 0)

  ;;; A documented variable
  (define baz 0)

  ;;; (procedure (foo X))
  ;;; A manual annotation in the first line of a comment overrides any auto-
  ;;; detected definition type. This is useful to mark closures, which scm2wiki
  ;;; would class as variable definitions otherwise.
  (define foo
    (let ((z #t))
      (lambda (x)
	(set! z x))))

  ;;; Since constants are not visible outside a translation unit, this constant
  ;;; is not included in the documentation.
  ;;; Override this behavior with the `--doc-internals` command line argument.
  (define-constant bar1 0)

  ;; An undocumented procedure
  (define (fooproc x)
    x)

  ;;; A documented procedure
  (define (bazproc y)
    (+ y y))

  ;;; (footax arg1 ...)
  ;;; A list expression at the start of a syntax comment is interpreted as
  ;;; the syntax' signature. scm2wiki does not auto-detect syntax signatures.
  (define-syntax footax
    (syntax-rules ()
      ((_ a ...) (list a ...))))

  ;;; A record type definition using defstruct
  (defstruct bla
    x ;;; a field comment
    y
    (z 1) ;;; another field comment
    )

  ;;; A record type definition using chicken/define-record
  (define-record blu x y)

  ;;; A record type definition using srfi-9
  (define-record-type blorb
    (make-blorb x y)
    blorb?
    (x blorb-x blorb-x-set!)
    (y blorb-y))

  ;;; A very simple coops class type defintion.
  (define-class <myclass> ()
    (foobar))

  ;;; A slightly more complex coops class definition derived from `<myclass>`.
  (define-class <mysubclass> (<myclass>)
    (foo
     (bar 0)
     (baz initform: 0 accessor: myclass-baz)))

  ;;; A procedure specialization on <mysubclass>.
  (define-method (do-foo primary: (baz <mysubclass>) another-arg)
    42)

  ) ;; end module foo

The resulting Markdown output:

# A Test Heading
## [module] foo

A stand-alone comment stretching multiple lines
*with* `formatting` **and** a [named link](https://call-cc.org)

` ` `Scheme
;; A fenced code block
(+ 1 2 3)
` ` `

an   | interesting | table
---- | ----------- | -----
with | actual      | content

#### [variable] `bar`
**default:** `0`


#### [variable] `baz`
**default:** `0`
A documented variable


#### [procedure] `(foo X)`
A manual annotation in the first line of a comment overrides any auto-
detected definition type. This is useful to mark closures, which scm2wiki
would class as variable definitions otherwise.


#### [procedure] `(fooproc X)`



#### [procedure] `(bazproc Y)`

A documented procedure


#### [syntax] `(footax ARG1 ...)`

A procedure signature at the start of a syntax comment is interpreted as
the syntax' signature. scm2wiki does not auto-detect syntax signatures.


### [record] `bla`
**[constructor] `(make-bla #!key X (Y 1) (Z 1))`**
**[predicate] `bla?`**
**implementation:** `defstruct`

field | getter  | setter       | default | type     | comment
----- | ------- | ------------ | ------- | -------- | ------------------------------
`x`   | `bla-x` | `bla-x-set!` |         |          | `a field comment`
`y`   | `bla-y` | `bla-y-set!` | `1`     |          |
`z`   | `bla-z` | `bla-z-set!` | `1`     | `number` | `a field with type annotation`

A record type definition using defstruct


### [record] `blu`
**[constructor] `(make-blu X Y)`**
**[predicate] `blu?`**
**implementation:** `define-record`

field | getter  | setter
----- | ------- | ------------
`x`   | `blu-x` | `blu-x-set!`
`y`   | `blu-y` | `blu-y-set!`

A record type definition using chicken/define-record


### [record] `blorb`
**[constructor] `(make-blorb X Y)`**
**[predicate] `blorb?`**
**implementation:** `srfi-9`

field | getter    | setter
----- | --------- | --------------
`x`   | `blorb-x` | `blorb-x-set!`
`y`   | `blorb-y` |

A record type definition using srfi-9


### [class] `<myclass>`
slot: `foobar`


A very simple coops class type defintion.


### [class] `<mysubclass>`
**inherits from:** [`<myclass>`](#class-ltmyclassgt)

slot  | initform | accessor
----- | -------- | -------------
`foo` |          |
`bar` | `0`      |
`baz` | `0`      | `myclass-baz`

A slightly more complex coops class definition derived from `<myclass>`.


**[method] `(do-foo primary: (BAZ <mysubclass>) ANOTHER-ARG)`**
A procedure specialization on <mysubclass>.

The resulting svnwiki output:

== A Test Heading
== Module foo

A stand-alone comment stretching multiple lines
''with'' {{formatting}} '''and''' a [[https://call-cc.org|named link]]

<enscript highlight=#"scheme#">;; A fenced code block
(+ 1 2 3)</enscript>



<table><tr><th>an   </th><th>interesting</th><th>table</th></tr>
<tr><td>with </td><td>actual</td><td>content</td></tr>

</table>

<constant>bar</constant>
; default : {{0}}


<constant>baz</constant>
; default : {{0}}
A documented variable


<procedure>(foo X)</procedure>

A manual annotation in the first line of a comment overrides any auto-
detected definition type. This is useful to mark closures, which scm2wiki
would class as variable definitions otherwise.


<procedure>(fooproc X)</procedure>



<procedure>(bazproc Y)</procedure>

A documented procedure


<syntax>(footax ARG1 ...)</syntax>

A procedure signature at the start of a syntax comment is interpreted as
the syntax' signature. scm2wiki does not auto-detect syntax signatures.


<record>bla</record>
; constructor : {{(make-bla #!key X (Y 1) (Z 1))}}
; predicate : {{bla?}}
; implementation : {{defstruct}}

<table><tr><th>field</th> <th>getter</th> <th>setter</th> <th>default</th> <th>type</th> <th>comment</th></tr><tr><td>{{x}}</td> <td>{{bla-x}}</td> <td>{{bla-x-set!}}</td> <td></td> <td></td> <td>{{a field comment}}</td></tr>
<tr><td>{{y}}</td> <td>{{bla-y}}</td> <td>{{bla-y-set!}}</td> <td>{{1}}</td> <td></td> <td></td></tr>
<tr><td>{{z}}</td> <td>{{bla-z}}</td> <td>{{bla-z-set!}}</td> <td>{{1}}</td> <td>{{number}}</td> <td>{{a field with type annotation}}</td></tr></table>

A record type definition using defstruct


<record>blu</record>
; constructor : {{(make-blu X Y)}}
; predicate : {{blu?}}
; implementation : {{define-record}}

<table><tr><th>field</th> <th>getter</th> <th>setter</th></tr><tr><td>{{x}}</td> <td>{{blu-x}}</td> <td>{{blu-x-set!}}</td></tr>
<tr><td>{{y}}</td> <td>{{blu-y}}</td> <td>{{blu-y-set!}}</td></tr></table>

A record type definition using chicken/define-record


<record>blorb</record>
; constructor : {{(make-blorb X Y)}}
; predicate : {{blorb?}}
; implementation : {{srfi-9}}

<table><tr><th>field</th> <th>getter</th> <th>setter</th></tr><tr><td>{{x}}</td> <td>{{blorb-x}}</td> <td>{{blorb-x-set!}}</td></tr>
<tr><td>{{y}}</td> <td>{{blorb-y}}</td> <td></td></tr></table>

A record type definition using srfi-9


=== Class <myclass>
<class><myclass></class>


; slot : {{foobar}}


A very simple coops class type defintion.



=== Class <mysubclass>
<class><mysubclass></class>

; inherits from : [[#Class-<myclass>|<myclass>]]

<table><tr><th>slot</th> <th>initform</th> <th>accessor</th></tr><tr><td>{{foo}}</td> <td></td> <td></td></tr>
<tr><td>{{bar}}</td> <td>{{0}}</td> <td></td></tr>
<tr><td>{{baz}}</td> <td>{{0}}</td> <td>{{myclass-baz}}</td></tr></table>

A slightly more complex coops class definition derived from {{<myclass>}}.


<method>(do-foo primary: (BAZ <mysubclass>) ANOTHER-ARG)</method>
A procedure specialization on <mysubclass>.

If you find that scm2wiki isn't suited for your needs, consider one of these alternatives:

• hahn
• schematic
• SchemeDoc

0.3.2 - Bugfix: Properly parse strings whose last character is a backslash, don't hide record definitions when their constructor is public

0.3.1 - Bugfix: Parenthesis characters are valid atoms

0.3.0 - Manual annotations for generic definitions, anchor links, various bugfixes

0.2.0 - Support for syntax, records, procedure signatures, coops classes

0.1.0 - initial release

• [markdown] transform variadic procedure definitions, svnwiki style
• [svnwiki] support for markdown lists, images, plain links, formatted text in tables
• [all] better support for type annotations
• [all] better support for macro definitions
• [all] better support for generics
• [all] support parameters
• [all] option to auto-generate TOC
• [markdown] remove unsupported svnwiki tags done
• [all] more robust command line arguments parsing done
• [all] support for macro, record, constant definitions etc. done

Contributions to scm2wiki are very welcome. See the above TODO list for issues that need help. If you're unsure how to contribute or have any questions, feel free to open an issue.