MPR#7333: Ocamldoc, use first sentence as a short description for text files in global overviews#784
Conversation
|
Your implementation is giving me pause. All existing occurrences of What happens if you instead keep the whole text values as |
|
This is tangentially related but in the context of the |
|
@gasche: You are right, the previous implementation was breaking the frontend/backend separation. I have pushed a new implementation that preserves this separation, at the price of a quick amending of the html generation for text only module (and some refactoring of the latex backend). @dbuenzli, would it not be more efficient to give the user a way to explicitly provide a synopsis or a brief description rather than use some arbitrary heuristic? |
It would but that doesn't address backwards compatibility. It seems that most people put their synopsis in its own paragraph (and ocamldoc syntax has a clear notion of paragraph). I think @dbuenzli's suggestion is that we might get away with using a saner heuristic without noticeably breaking backwards compatibility. |
|
Assuming that the new implementation is correct, it looks much more natural indeed. |
|
I went on to merge the change. Re. first sentence versus first paragraph. I see the point with "first paragraph" being a better-defined notion, but the module listing using the short descriptoins really call for a one-line description and not something longer. Assuming the first sentence is most often on its own paragraph anyway, changing to the first paragraph would probably not make much of a difference (I would support the change), but it is also a fairly orthogonal change to the current PR (at least in the new implementation state) as it applies to all source elements and not just text files. |
…n_for_txt MPR#7333: Ocamldoc, use first sentence as a short description for text files in global overviews
…rivate mode, etc. (ocaml#784)
25188da flambda-backend: Missed comment from PR802 (ocaml#887) 9469765 flambda-backend: Improve the semantics of asynchronous exceptions (new simpler version) (ocaml#802) d9e4dd0 flambda-backend: Fix `make runtest` on NixOS (ocaml#874) 4bbde7a flambda-backend: Simpler symbols (ocaml#753) ef37262 flambda-backend: Add opaqueness to Obj.magic under Flambda 2 (ocaml#862) a9616e9 flambda-backend: Add build system hooks for ocaml-jst (ocaml#869) 045ef67 flambda-backend: Allow the compiler to build with stock Dune (ocaml#868) 3cac5be flambda-backend: Simplify Makefile logic for natdynlinkops (ocaml#866) c5b12bf flambda-backend: Remove unnecessary install lines (ocaml#860) ff12bbe flambda-backend: Fix unused variable warning in st_stubs.c (ocaml#861) c84976c flambda-backend: Static check for noalloc: attributes (ocaml#825) ca56052 flambda-backend: Build system refactoring for ocaml-jst (ocaml#857) 39eb7f9 flambda-backend: Remove integer comparison involving nonconstant polymorphic variants (ocaml#854) c102688 flambda-backend: Fix soundness bug by using currying information from typing (ocaml#850) 6a96b61 flambda-backend: Add a primitive to enable/disable the tick thread (ocaml#852) f64370b flambda-backend: Make Obj.dup use a new primitive, %obj_dup (ocaml#843) 9b78eb2 flambda-backend: Add test for ocaml#820 (include functor soundness bug) (ocaml#841) 8f24346 flambda-backend: Add `-dtimings-precision` flag (ocaml#833) 65c2f22 flambda-backend: Add test for ocaml#829 (ocaml#831) 7b27a49 flambda-backend: Follow-up PR#829 (comballoc fixes for locals) (ocaml#830) ad7ec10 flambda-backend: Use a custom condition variable implementation (ocaml#787) 3ee650c flambda-backend: Fix soundness bug in include functor (ocaml#820) 2f57378 flambda-backend: Static check noalloc (ocaml#778) aaad625 flambda-backend: Emit begin/end region only when stack allocation is enabled (ocaml#812) 17c7173 flambda-backend: Fix .cmt for included signatures (ocaml#803) e119669 flambda-backend: Increase delays in tests/lib-threads/beat.ml (ocaml#800) ccc356d flambda-backend: Prevent dynamic loading of the same .cmxs twice in private mode, etc. (ocaml#784) 14eb572 flambda-backend: Make local extension point equivalent to local_ expression (ocaml#790) 487d11b flambda-backend: Fix tast_iterator and tast_mapper for include functor. (ocaml#795) a50a818 flambda-backend: Reduce closure allocation in List (ocaml#792) 96c9c60 flambda-backend: Merge ocaml-jst a775b88 flambda-backend: Fix ocaml/otherlibs/unix 32-bit build (ocaml#767) f7c2679 flambda-backend: Create object files internally to avoid invoking GAS (ocaml#757) c7a46bb flambda-backend: Bugfix for Cmmgen.expr_size with locals (ocaml#756) b337cb6 flambda-backend: Fix build_upstream for PR749 (ocaml#750) 8e7e81c flambda-backend: Differentiate is_int primitive between generic and variant-only versions (ocaml#749) git-subtree-dir: ocaml git-subtree-split: 25188da
* Suggested edits to guidelines document Tightening syntax, consistency in formatting, grammar, etc. * updated `lets` to `let` statements and fixed destructuring
4 participants
MPR#7333:
In global overviews, ocamldoc uses the first sentence of documentation comments as a short description
of the content of the module/file for
.mliand.mlfiles, but not for simple text file. As suggested in the linked mantis ticket, this pull request fixes this asymmetry and uses the first sentence of a text file as a short description of this file in global overviews.