Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

various documentation problems #4292

Closed
vicuna opened this issue May 24, 2007 · 4 comments
Closed

various documentation problems #4292

vicuna opened this issue May 24, 2007 · 4 comments

Comments

@vicuna
Copy link

vicuna commented May 24, 2007

Original bug ID: 4292
Reporter: Hendrik Tews
Status: closed (set by @xavierleroy on 2013-08-31T10:48:44Z)
Resolution: fixed
Priority: normal
Severity: minor
Version: 3.10.0
Fixed in version: 4.00.0+dev
Category: ocamldoc
Related to: #8336
Monitored by: @zoggy

Bug description

Some of these points are very minor, but I thought I tell
everything I spotted and let you decide...

  1. AGAIN AND AGAIN AND AGAIN: PLEASE MAKE THE SOURCES OF THE
    DOCUMENTATION AVAILABLE [or produce a manual with changes
    information yourself] I am begging for this for years already!

  2. the positional specifier for width and precision of printf
    format strings is poorly described

  3. the tar file with html version of the manual contains strange
    files, eg manual.haux

  4. the comment of UnixLabels.wait_flag refers to module Unix

  5. type in Genarray.map_file: default->defaults

  6. online doc pointer in
    http://caml.inria.fr/ocaml/release-prev.en.html points to the
    3.10 docs

  7. in bscanf, its unclear what "bounding condition" means

  8. format6 is missing in the builtin types

  9. in the txt version, explanations of embedded modules are
    displaced, for instance "Scanning buffers" appears as headline
    after the contents of the Scanf.Scanning module

  10. capiltal format string letters are treated as constructors:
    F

  11. the comment on Pervasives.format4 is general and should
    follow the heading directly

  12. wrong open_in in open_in_gen description

  13. use the meta symbol class-body in class-expr

  14. in the txt version: formatting error in the 3rd case of
    variant-type

  15. [might be a feature] some file names have changed, eg
    lex.html instead of manual009.html

  16. in the txt version, the first line of embedded output is
    behind the << marker, eg

<<#1+2*3;;

  • : int = 7
  1. wrong version used:
    <<##load "camlp4o.cma";;
    Camlp4 Parsing version 3.10+dev26 (2007-04-25)
@vicuna
Copy link
Author

vicuna commented May 25, 2007

Comment author: @pierreweis

Points No 4, 6, 10, 11 are corrected in the working sources.
Point 1 will be worked out soon, when the positional specifiers implementation is either finished or abandoned at the end of next month.

Thank you for the careful review.

@vicuna
Copy link
Author

vicuna commented May 25, 2007

Comment author: @pierreweis

Points No 3 also corrected.

@vicuna
Copy link
Author

vicuna commented Feb 7, 2012

Comment author: @damiendoligez

0: it is now available at http://caml.inria.fr/cgi-bin/viewvc.cgi/ocamldoc/
1: done (positional specifiers were removed).
2: fixed in trunk [3.13.0] (commit 12138)
5: done by fixing #8336
7: fixed in trunk [3.13.0] (commit 12135)
12: fixed in trunk [3.13.0] (commit 12137)
14: it's a feature
15: Not sure what you mean by "behind". It is indented by 2 spaces, which puts it right after the marker.
16: correct in 3.12.1

That leaves us with:
8: but look for "Formatted input channel" instead of "Scanning buffers"
9:
13: should be indented more, but look for "polymorphic-variant-type" instead of "variant-type"

8 and 13 are most probably ocamldoc bugs, not sure about 9.

@vicuna
Copy link
Author

vicuna commented Mar 13, 2012

Comment author: @damiendoligez

8 is fixed. It was a mistake in Scanf.mli: a missing blank line between the header comment and the module declaration meant that the header comment was the description of the module, which was properly printed after the module declaration by ocamldoc. (commits 12230 and 12231)

13 is a bug/limitation of Hevea, not ocamldoc.

About 9: it's a problem that we'll have to live with. Using another notation in the .mli would make it rather unreadable.

I'm closing this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant