Add interface doc #571
Add interface doc #571
Conversation
Signed-off-by: Jon Ludlam <jon@recoil.org>
|
|
||
| {2 Output formats} | ||
|
|
||
| Odoc currently outputs HTML files, man pages and latex documents. In a similar vein to the CLI interface, |
There was a problem hiding this comment.
from the odoc dev meeting: need a statement of intermediate file formats as well (e.g. are odoc files supported)
src/odoc/interface.mld
Outdated
|
|
||
| - odig | ||
| - dune | ||
| - ocaml |
There was a problem hiding this comment.
odoc dev meeting: note that this is OCaml 4.12.0 onwards
src/odoc/interface.mld
Outdated
| - Comments describing class inheritance are not rendered (bug) | ||
| - Odoc does not currently handle ambiguously associated doc comments (bug) | ||
| - Odoc does not ignore tags where they don't make sense (e.g. [@param] tags on instance variables are rendered) (bug) | ||
| - {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#ss:ocamldoc-formatting}Alignment elements} are not handled ([{C text}], [{L text}] and [{R text}]) | ||
| - Odoc does not recognise {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sss:ocamldoc-html-tags}html tags embedded in comments} |
There was a problem hiding this comment.
from dev meeting: turn these into bugs on github and link as they will be fixed
src/odoc/interface.mld
Outdated
|
|
||
| {4 Improvements} | ||
| - Odoc has a better mechanism for disambiguating references in comments. See 'reference syntax' later in this document. | ||
| - Support for standalone 'mld' files - these are documents using the OCamldoc markup, but rendered as distinct pages. |
There was a problem hiding this comment.
Maybe built-in support for mld files? ocamldoc supports documentation-only "modules" with the --text option.
| Odoc has several internal libraries. The only one of these for which we currently expect external users is | ||
| the comment parser. This will soon be removed into an external package to link with separately and will | ||
| have its own lifecycle and support statement. Note that this will perform the same function as the existing | ||
| [octavius] library, which was the original implementation of odoc's current parser. |
There was a problem hiding this comment.
can this replace octavius instead of sitting alongside it? there should be no valid usecases of octavius after this odoc parser is pulled out
| + [@returns] is a synonym for [@return] | ||
| + [@raises] is a synonym for [@raise] | ||
| + [@open] and [@closed] and [@inline] are hints for how 'included' signatures should be rendered | ||
| + [@canonical] allows a definition of a module to be marked as canonically elsewhere. |
There was a problem hiding this comment.
@lpw25 from dev meeting: we dont support !modules and the list of modules, and the table of contents is also unsupported. These are omissions.
There was a problem hiding this comment.
Except or the lack of synopsis !modules is perfectly supported. I use it in almost every of my packages out there and in odig's automatic index.mld generation for packages that do not provide one.
There was a problem hiding this comment.
I've added {!indexlist} in the omissions and added the issue @dbuenzli mentioned to the 2.0 milestone.
| + [@raises] is a synonym for [@raise] | ||
| + [@open] and [@closed] and [@inline] are hints for how 'included' signatures should be rendered | ||
| + [@canonical] allows a definition of a module to be marked as canonically elsewhere. | ||
|
|
Co-authored-by: Anil Madhavapeddy <anil@recoil.org>
Signed-off-by: Jon Ludlam <jon@recoil.org>
Signed-off-by: Jon Ludlam jon@recoil.org