|Anonymous | Login | Signup for a new account||2017-11-20 12:28 CET|
|Main | My View | View Issues | Change Log | Roadmap|
|View Issue Details|
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0007646||OCaml||ocamldoc||public||2017-09-29 03:08||2017-10-01 19:50|
|Target Version||Fixed in Version|
|Summary||0007646: ocamldoc should generate a 'table of contents' for each module page|
|Description||The idea is to put an easily-scannable (and hyperlinked) listing of the module's contents near the top of the page so that the user can quickly look through what's available and click to jump down to any item they're interested in.|
See https://discuss.ocaml.org/t/proposal-ocamldoc-should-generate-a-table-of-contents-in-each-module-page/871 [^] for an example.
|Additional Information||I'm working on a proof-of-concept of this on my branch at https://github.com/yawaramin/ocaml/tree/ocamldoc-toc [^]|
|Personally I don't feel this would improve documentation usability.|
edited on: 2017-09-29 16:53
I think it's a good compromise between the current layout and what you suggested in https://discuss.ocaml.org/t/first-installment-of-lwts-new-manual/815/2?u=yawaramin [^] :
> In my opinion it’s better to discuss things more extensively in dedicated sections (e.g. at the end of the module) and link to that from the doc strings.
So what I'm proposing is we don't need to change any current docstrings, and instead provide a quick overview with links so the reader can jump down to these descriptions. It solves the problem (at least to some extent) you identified:
> This makes it difficult to navigate the API and see what it actually offers, which once you get familiar with the API becomes your main interaction pattern and the one you should optimize for.
With an overview section of just names and descriptions, the interaction pattern is quickly scanning to find exactly what you were looking for, and then jumping down to the details if necessary. It's functionally equivalent to your proposed interaction.
|@yawaramin: the best way to go is to submit your work as a Github pull request when it is ready.|
|@xleroy: thanks, I'm planning to send a PR very soon. For best results, I want to wait for https://caml.inria.fr/mantis/view.php?id=7635 [^] , octachron is working on generating linkable IDs for modules and module types. The table of contents I have so far is nice but it will be even nicer with that.|
|PR sent https://github.com/ocaml/ocaml/pull/1385 [^]|
@yawaramin In my opinion the problem there stems from trying to mix a manual with API reference. As such I rather see it as a problem with the approach taken in documenting that library rather than ocamldoc's markup itself.
In some sense if your functions need loads of text to describe what they are doing you should rather revise your API... The current layout works well for the M.t pattern and in most cases, it has a good scrolling/scanning/access to details efficiency.
What you suggest will in my opinion add more noise for small to medium size modules and also destroy a few useful interaction that are available in the current layout (e.g. in-page browser search takes you directly to the full description of a given symbol with high probability).
It is possible to section your symbols by functionality and nothing prevents you from providing direct links to the section in a well-designed and written module introduction which may work better than a per symbol toc.
@dbuenzli I agree with your concerns about increasing the noise level for small-to-medium modules and preserving in-page search interaction. Please take a look at https://discuss.ocaml.org/t/proposal-ocamldoc-should-generate-a-table-of-contents-in-each-module-page/871?u=yawaramin [^] , I believe by putting the module TOC in a (by default collapsed) expandable section, I address both the concerns.
Re: mixing manual with API reference and designing module documentation, I believe module docs are our best hope of encouraging developers to write good docs, be they manual style, tutorial style, or API reference style. The easier we make it for them, the more everyone benefits. This is more of a philosphical argument though, for now you can check out the above link to see where I want to take ocamldoc output in the medium term.
|2017-09-29 03:08||yawaramin||New Issue|
|2017-09-29 08:42||dbuenzli||Note Added: 0018392|
|2017-09-29 16:50||yawaramin||Note Added: 0018395|
|2017-09-29 16:51||yawaramin||Note Edited: 0018395||View Revisions|
|2017-09-29 16:53||yawaramin||Note Edited: 0018395||View Revisions|
|2017-09-29 19:53||xleroy||Note Added: 0018400|
|2017-09-29 19:53||xleroy||Status||new => acknowledged|
|2017-09-30 00:48||yawaramin||Tag Attached: ocamldoc|
|2017-09-30 00:50||yawaramin||Note Added: 0018408|
|2017-10-01 00:23||yawaramin||Note Added: 0018434|
|2017-10-01 19:20||dbuenzli||Note Added: 0018443|
|2017-10-01 19:50||yawaramin||Note Added: 0018444|
|Copyright © 2000 - 2011 MantisBT Group|