Closed dbuenzli closed 4 years ago
This sounds like a good idea and I believe this is the appropriate repository. I'm swapping into codoc soon and code snippet handling is perhaps the largest embedded content issue as far as I can tell.
See http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sec328 for the feature that could be co-opted to support this.
In my libraries I often provide sample code, sometimes it's only snippets separated by comments in a litterate programming fashion (see e.g.
Vg
's basics) sometimes it is full working examples (see e.g.Cmdliner
's full examples).Usually I have a copy of this code in my
test/
directory (they are part of thetest
compilation target) and I install that in the documentation directory of the package, see e.g.:The problem is of course that this sample code is not type-checked and needs to be kept in sync with the files manually which from a maintenance point of view is error-prone an painful in general. Still I think that this way of doing is the right way (i.e. always keep all documentation bits with the mli themselves).
It would be nice if some kind of code extraction facility could be provided by the tool. However I don't see how this could be done without extending the
ocamldoc
language.The idea would be that code fences (
{[ ... ]}
) should support arbitrary identifiers of some sort e.g.{$ID[ ... ]}
if that's possible parsing-wise.codoc
would then provide acode-extract
command, that provided with an identifiers would extract andcat
all the fences with that identifiers. This would allow to build the sources of the sample code by doing acodoc code-extract $ID m.xml > examples.ml
.I guess this doesn't strictly belongs to codoc but I'm filing this here since this is the end-user front-end. Feel free to direct me to the appropriate bug tracker(s).