Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0006425OCamlOCamldocpublic2014-05-16 09:302014-09-08 15:12
Reporteravsm 
Assigned Toguesdon 
PrioritynormalSeveritymajorReproducibilityalways
StatusclosedResolutionfixed 
PlatformOSOS Version
Product Version 
Target Version4.02.0+devFixed in Version 
Summary0006425: ocamldoc isn't creating all the manual pages in 4.02/3
DescriptionAfter making ocamldoc/stdlib_man, some pages (such as Format.3o) are now missing. They were built previously in 4.01, and the corresponding HTML pages in stdlib_html are still present. This points to an issue in the ocamldoc man page backend.
Steps To ReproduceDo a build and (results below from Gabriel)

$ ls -1 stdlib_html/* | grep "/[A-Z][a-zA-Z_]*.html" | grep "/[A-Z][a-zA-Z_]*." -o | sort > /tmp/dochtml
$ ls -1 stdlib_man/* | grep "/[A-Z][a-zA-Z_]*.3o" | grep "/[A-Z][a-zA-Z_]*." -o | sort > /tmp/docman
$ diff /tmp/doc{html,man}
13d12
< /Char.
17d15
< /Format.
21d18
< /Lazy.
28d24
< /Nativeint.
39d34
< /Set.
45d39
< /String.
TagsNo tags attached.
Attached Files

- Relationships

-  Notes
(0011492)
gasche (developer)
2014-05-16 16:24

I bisected this to a surprising result: the faulty change is my own commit
  "Use a nominal datatype for CamlinternalFormat.format6"
It seems to breaks manpage generation under either trunk or 4.02 -- while totally unrelated.

Investigating.
(0011495)
doligez (administrator)
2014-05-16 17:40

This is an ocamldoc bug triggered by the option -man-mini:

       -man-mini
              Generate man pages only for modules, module types, classes and
              class types, instead of pages for all elements.

What all these modules have in common, is that there are data constructors of the same names in other modules. When I remove the constructors from the type declarations in their respective .mli files, the man pages of these modules are output as expected.

I have not looked at the ocamldoc code so I've no idea how to fix it, but this one is clearly for Maxence.
(0011540)
guesdon (manager)
2014-05-22 08:55

I'm looking at this.
(0011542)
guesdon (manager)
2014-05-22 09:35

When the -man-mini is not given, ocamldoc generates a .3o file for each value,type,..., name. This file lists the occurrences of this name and the module it belongs to. For example, iter.3o will list Bytes.iter, Array.iter, ...

Of course, when a variant constructor has the same name as a module, both should be listed in a common file, for example Format.3o. But with the -man-mini option, only files corresponding to one class [type] or one module [type] are created, hence the missing files. I say "should" because in fact record fields, variant constructors and modules are not listed in such .3o files. (for example, the Format.3o file generated without -man-mini option does not list any elements). I'll add some code to list them, hoping the resulting man page will not be too unpleasant to read.

Another, simpler, solution is to "forget" variant constructors, preventing conflict with module names.
(0011543)
guesdon (manager)
2014-05-22 10:39

Fixed in revisions 14901(version/4.02) and 14902(trunk).
When the -man-mini option is passed, only classes, class types, modules and module types are kept to generate .3o files. The previous filter preventing the generation of .3o files containing more than one element is removed.

- Issue History
Date Modified Username Field Change
2014-05-16 09:30 avsm New Issue
2014-05-16 16:24 gasche Note Added: 0011492
2014-05-16 17:40 doligez Note Added: 0011495
2014-05-16 17:41 doligez Assigned To => guesdon
2014-05-16 17:41 doligez Status new => confirmed
2014-05-16 17:41 doligez Category OCaml documentation => OCamldoc
2014-05-16 17:41 doligez Target Version => 4.02.0+dev
2014-05-22 08:55 guesdon Note Added: 0011540
2014-05-22 09:35 guesdon Note Added: 0011542
2014-05-22 10:39 guesdon Note Added: 0011543
2014-05-22 10:39 guesdon Status confirmed => resolved
2014-09-08 15:12 guesdon Status resolved => closed
2014-09-08 15:12 guesdon Resolution open => fixed


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker