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

some problems in the 4.01 documentation #6189

Closed
vicuna opened this issue Sep 24, 2013 · 7 comments
Closed

some problems in the 4.01 documentation #6189

vicuna opened this issue Sep 24, 2013 · 7 comments

Comments

@vicuna
Copy link

vicuna commented Sep 24, 2013

Original bug ID: 6189
Reporter: Hendrik Tews
Assigned to: @damiendoligez
Status: feedback (set by @damiendoligez on 2014-01-22T15:23:28Z)
Resolution: open
Priority: normal
Severity: minor
Version: 4.01.0
Category: documentation
Tags: junior_job
Monitored by: @gasche warwick

Bug description

Hi,

as always, I am reporting some points that I found during the
preparation of the enhanced OCaml documentation. As always, some
of these points are bugs but for others I am not sure.

  1. the compiler accepts ``for (+) = 2 to 2 print_int (+) done'',
    is this really intended?

  2. some ocamlopt options are not documented, for instance -nostdlib

  3. in ocamldoc.html, the references for {% string %} and
    {! string } in 15.2.4 point to some sub-sub-section, but they
    print as 15.2.4, which is not really helpful, especially in
    the pdf version.

  4. in 15.3.1, the links the some source code examples point to
    4.00 versions of these files.

  5. the functions Format.set_all_formatter_output_functions and
    Format.get_all_formatter_output_functions are new in 4.01 and
    not deprecated since 4.00.

  6. The documentation of Format.set_formatter_out_functions
    mentions the functions out_string and out_flush, which, IMO,
    do not exists.

  7. In the 4.00 docs, the pretty printing indication @@ was
    deprecated. Now, it is not deprecated any more, but it is still
    recommended to use %@.

  8. In libref/Scanf.html, why are there backslashes in the
    conversion specification ( fmt %), when the examples use no
    backslashes?

  9. In libref/Scanf.html, the paragraph after the conversion spec
    ( fmt %) seems to be wrongly indented.

  10. In libref/Unix.html, the sentence "The flags to
    Unix.openfile.", which follows the doc entry for open_flag,
    is not properly indented.

  11. In libref/Str.html, in the doc entry for matched_string,
    there seems to be a formatting error following
    Str.substitute_first.

  12. In classes.html, section 6.9.2, subsection "Method
    definition", there is a list of the special expressions
    available in method bodies. IMHO, the expression consisting
    just of "inst-var-name" is missing there.

Bye,

Hendrik

@vicuna
Copy link
Author

vicuna commented Oct 8, 2013

Comment author: @damiendoligez

About (1): yes of course it is really intended. Just like "let (+) = 2 in print_int (+)".

@vicuna
Copy link
Author

vicuna commented Jan 22, 2014

Comment author: @damiendoligez

(2) fixed (commit 14409 in 4.01, 14410 in trunk, 14414 in manual)

(5) I don't understand. The function is not new in 4.01, it was already there in 3.12.1. It's deprecated since 4.01.0. The source is still wrong, because it says the function was introduced in 4.00.0. fixed in trunk (commit 14411)

(6) The text was a bit cumbersome. fixed in trunk (commit 14411)

(7) @@ didn't work in 4.00, now it does.

@vicuna
Copy link
Author

vicuna commented Jan 22, 2014

Comment author: @damiendoligez

(8): it's a bug. fixed in trunk (commit 14412)
(9) fixed in trunk (commit 14412)

@vicuna
Copy link
Author

vicuna commented Jan 22, 2014

Comment author: @damiendoligez

(10) and (11) fixed in trunk (commit 14413)

(12): syntactically, inst-var-name is just a lowercase-ident, which is included in value-path, which itself is already in expr. So adding it there would be redundant from a formal point of view. Do you think it would make the documentation easier to read?

(3) and (4) fixed in trunk (commit 14414)

The only remaining point is (12) to be discussed.

@vicuna
Copy link
Author

vicuna commented Apr 8, 2015

Comment author: warwick

G'day … this is really minor, so I hope you don't mind me mentioning it here as a note.

In array.mli could you add another heading to the documentation by putting

(** {6 Iterators} *)

at line 124. Then moving the Array.make_float section up to underneath Array.make.

The extra subheading would make the Array documentation easier to read and be more consistent with the List documentation.

Thanks.

@vicuna
Copy link
Author

vicuna commented Apr 18, 2016

Comment author: @damiendoligez

@warwick, this was done as part of #230 ( #230 )

@Octachron
Copy link
Member

I think it is better to leave out the inst-var-name case from the list of expressions only allowed in method definitions.

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

3 participants