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

ocamldoc: @param tags #8804

Open
rudelune opened this issue Jul 14, 2019 · 3 comments

Comments

@rudelune
Copy link

commented Jul 14, 2019

Hello,
I'm trying to use ocamldoc and especially printing arguments of functions via the tag @param <variable name> <description> which is described in the documentation (http://caml.inria.fr/pub/docs/manual-ocaml-4.08/ocamldoc.html section 15.2.5).

The command that I use is ocamldoc.opt -I `ocamlfind query zarith` [-load ...] -load utils.odoc -all-params -html -d analyser.docdir.
I use the option -all-params to show all the parameters of the functions.

In fact, I have in the module Utils the following code:
(** Return the last location of a program
@param block The block of C/ASM located statements
@return The last location of the block *)
let lastLocOfProgram (program : loc * ('a * loc) list) : loc =
and in the documentation generated I have that result:
github-problem1

However, if I use just the name of the part of an argument, it works:
(** Remove the labels of the program and replace them by the locations associated
@param program The located program
@return The located program with the labels which have been replaced *)
let removeLabelsProgram (l1, program : program) : program =
github-problem2

But I don't really understand why.

Thank you in advance for your reading.

rudelune

@Octachron

This comment has been minimized.

Copy link
Contributor

commented Jul 14, 2019

There are two issues going on simultaneously here.
First, ocamldoc always ignore @param tags which does not match any named argument in the the implementation of the function, thus in

(** Return the last location of a program
@param block The block of C/ASM located statements
@return The last location of the block *)
let lastLocOfProgram (program : loc * ('a * loc) list) : loc =

the line @param block ... is ignored because the only named argument in the function implementation is program.

Second, it seems that ocamldoc does not know how to extract argument names when a single argument is explicitly annotated as a tuple.
This second point is definitely a bug.

Note that those two problems do not affect your second example.

Thus an easy workaround four your first example would be to both
use the same name in the function implementation and the param tag (i.e. either block or program) and remove the explicit type annotation.

@dbuenzli

This comment has been minimized.

Copy link
Contributor

commented Jul 15, 2019

@rudelune if you are new to ocaml, I think it may also be useful to add that @param and @return have been little used in practice by document writers and may not be that well supported (e.g. in odoc).

A good pattern you'll find in part of stdlib itself (see for example the documentation of the Array module) is to have a sample function call that names your arguments and then have a free form text describing the resulting value of the function using the argument names.

Applying the pattern to your case, a more idiomatic way would be:

(** [lastLocOfProgram p] is the the last location of the block of located statements [p]. *)
(** [removeLabelsProgram p] is the program [p] with its labels replaced by their associated locations. *)
@rudelune

This comment has been minimized.

Copy link
Author

commented Jul 15, 2019

Hello!
Thank you so much for your answers! I just took THE function is which the variable's name wasn't the name given to the param tag x)
You are right, without the type annotation it works well!
In fact I want to keep the syntax with param tags given that I want to give the documentation to my reviewers. That's why I can't use odoc which generates documentation only for libraries (not executables).

Do you think that I would leave this issue unclosed because of the bug about types annotation?

Thank you again!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.