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.

Reply via email to