Stdlib: Documentation style for stdlib

[vansnyder]

The stdlib should be packaged in modules, each one a coherent set of related procedures (and types and constants). These should ultimately all be described in a consistent style, as (or at least as if) an optional part of the standard. Procedures should be described in the same format as in subclause 16.9 of part 1 of the standard. Constants and opaque types can be described as in subclause 16.10. Types that have public components and bindings could be described by a type definition that shows only type parameters, and the public components and bindings. Type-bound procedures should be described as in subclause 16.9. I prepared my proposal for special functions in this format.

[jvdp1]

Thank you @vansnyder for your comments.

Procedures should be described in the same format as in subclause 16.9 of part 1 of the standard.

Good point. The current format (see example here for stdlib_experimental_stats ) should probably slightly modified if we want to follow exactly the same format as in the standard.

[milancurcic]

I think this is a good plan for the specification docs. It would also ease the transition to the standard if and when it's proposed. Then we could evolve a specification doc -> J3 paper.

We'll also need a separate set of user friendly docs but we're not there yet.

[jacobwilliams]

I must admit I am not a huge fan of the format required by the standard. The priority should be the user-facing documentation, which needs to be dynamic, web based, should have syntax highlighting, links, etc. Nobody is going to be printing this stuff out in book form, so we shouldn't be limited to that format.

[milancurcic]

I don't like the standard format either, but both are important. One of the original motivations behind stdlib is to implement and evaluate in practice functions before proposing them to J3. Documenting the spec in the standard format would save us from a lot of work later. Another question is whether there is much value to have a built-in function if there is one in a stable and portable stdlib (I don't think so).

I agree that user-docs are higher priority. But we haven't done any work toward that, except some docstrings inside the code itself, which I don't think is the best solution either.

Jacob, can you help with the user-docs?

[jvdp1]

I agree that the standard format is too minimalist and that the user-docs is more important.
But it would be nice if we could extract what is needed for the standard directly from stdlib user-docs, and I think that the current format (that contains e.g. more verbose examples) is quite close to allow it.

[zbeekman]

The specs and user documentation don't need to be the same. User documentation could be less formal and have more/richer examples and point to the spec for detailed reference? It's hard to have an exceedingly strong opinion without also being willing to work up a PR (or two... or a dozen) to prototype and/or implement the proposal.