Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0007646OCamlocamldocpublic2017-09-29 03:082017-10-01 19:50
Reporteryawaramin 
Assigned To 
PrioritynormalSeverityfeatureReproducibilityalways
StatusacknowledgedResolutionopen 
PlatformOSOS Version
Product Version 
Target VersionFixed in Version 
Summary0007646: ocamldoc should generate a 'table of contents' for each module page
DescriptionThe 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 InformationI'm working on a proof-of-concept of this on my branch at https://github.com/yawaramin/ocaml/tree/ocamldoc-toc [^]
Tagsocamldoc
Attached Files

- Relationships

-  Notes
(0018392)
dbuenzli (reporter)
2017-09-29 08:42

Personally I don't feel this would improve documentation usability.
(0018395)
yawaramin (reporter)
2017-09-29 16:50
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.

(0018400)
xleroy (administrator)
2017-09-29 19:53

@yawaramin: the best way to go is to submit your work as a Github pull request when it is ready.
(0018408)
yawaramin (reporter)
2017-09-30 00:50

@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.
(0018434)
yawaramin (reporter)
2017-10-01 00:23

PR sent https://github.com/ocaml/ocaml/pull/1385 [^]
(0018443)
dbuenzli (reporter)
2017-10-01 19:20

@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.
(0018444)
yawaramin (reporter)
2017-10-01 19:50

@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.

- Issue History
Date Modified Username Field Change
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
Powered by Mantis Bugtracker