What do people think about the following way of providing Scribble API
documentation from a module?
* The Scribble documentation for a package comes from a combination of
the package's `info` module and inline documentation from one or modules
that make up the package.
* The exact form of inline documentation is unspecified for this purpose
(it could come entirely from `@doc{ ... }` forms, or from docstrings,
and/or derived from language forms such as type signatures).
* A module has a `doc` submodule that `provide`s at least one thing: a
`doc-stx`, which collects the *syntax objects* for all the documentation
defined or inferred for that module. `doc-stx` has no dependency on
Scribble modules, but can be used with them. (This gives some
flexibility for `#lang`s and evolution to do it different ways, while
providing the same interface that's more powerful than static `.scrbl`
source files.)
* The source location info in `doc-stx` reflects where each bit of
Scribble came from (e.g., `defproc` argument type syntax objects derived
from parts of a contract signature have those parts of the contract form
as their source location).
* The ordering of the eventual Scribble documentation for a package is
mostly the ordering of the embedded documentation, which means mostly
the ordering of `provide`d code definitions. (Doing this for dozens of
packages, for over a decade, my impression is that this is not a
problem, though it encourages bottom-up API documentation.)
* For embedded documentation spread across multiple modules of a
package, the ordering of the modules's documentation would be specified
by having a top-level document
* The headings level of `doc-stx` syntax objects can also be adjusted
when they are included in a larger document, such as by routinely using
`section` as the top heading level of any module, but optionally being
able to shift that down/up one or more levels when including it in
another document.
* For now, the `doc-stx` would be used only for running Scribble to
generate HTML manuals, but you could imagine it later being used
directly by an IDE. (Initially, to work with current Racket tools,
there would be a shim `.scrbl` file generated for each package, which
dynamically pulls the documentation out of the appropriate `doc`
submodules.)
* In addition to the `doc` submodule providing `doc-stx`, it could later
also provide additional things, such as precomputed indexes, or future
documentation-ish semantics that doesn't reduce to `racket/base` code or
Scribble. For now, the biggest win is `doc-stx` Scribble syntax objects
that go to HTML manuals, but we keep the option to grow gracefully from
there.
BTW, the context of this is query is that I'm refining some optional
"lightweight language" tweaks to a `#lang` that's mostly `racket/base`.
This would initially be focused on simplifying some good routine
practices for unit testing, documentation, and then `info` metadata.
This would interoperate with all the other `#lang`s, but some people
will find it much more convenient than `#lang racket` when building
systems out of components made from the start to be reusable.
--
You received this message because you are subscribed to the Google Groups "Racket
Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
