Skip to content

docstrings#477

Merged
mshinwell merged 4 commits intoocaml:4.03from
trefis:4.03-docstrings
Mar 3, 2016
Merged

docstrings#477
mshinwell merged 4 commits intoocaml:4.03from
trefis:4.03-docstrings

Conversation

@trefis
Copy link
Copy Markdown
Contributor

@trefis trefis commented Feb 22, 2016

This PR adds support for documentation comments in the following positions:

  1. on the parameters of a function type:
    type 'a with_optionnal = ?optionnal:unit (** optionnal! *) -> 'a
    val f : ?foo:int (** default [0] *) -> bar:string (** doc *) -> unit (** doc *) -> unit
  2. inside polymorphic variant types:
    type t = [ Foo (** foo! *) | Bar of int * string (** bar? *) ]
  3. inside object types:
    type t = < foo: int -> int (** foo *) ; bar: int -> int; (** bar *) .. >

Currently if warning 50 is enabled it will be emitted for every comment of the examples above.
This is unfortunate because people have not only been asking support for this for a while (see various issues on mantis), but have also been using that style while waiting for tooling support, see:

  • examples of polymorphic variants documentation: here and there
  • examples of function parameters annotations: here and there,
  • example of an object type definition with annotations on methods: here

One should note that the warning inside object types as support was added in ocamldoc with this commit (cf. mantis PR#6274).

The other two cases were not supported but remove an unnecessary limitation and conforms with the style people are already using.

@trefis trefis changed the title 4.03 docstrings docstrings Feb 22, 2016
@mshinwell
Copy link
Copy Markdown
Contributor

Apparently @damiendoligez has said this would go in 4.03

@mshinwell mshinwell added this to the 4.03.0 milestone Feb 24, 2016
@trefis
Copy link
Copy Markdown
Contributor Author

trefis commented Feb 29, 2016

I rebased the changes this morning, the failing tests are:

@trefis
Copy link
Copy Markdown
Contributor Author

trefis commented Feb 29, 2016

@diml just fixed the camlp4 problem.
The rest is up to @mshinwell .

@mshinwell
Copy link
Copy Markdown
Contributor

@damiendoligez Is this ok to merge?

@damiendoligez
Copy link
Copy Markdown
Member

Yes, OK to merge.

@damiendoligez damiendoligez mentioned this pull request Mar 3, 2016
@trefis trefis force-pushed the 4.03-docstrings branch from 6f550f5 to 3fee64a Compare March 3, 2016 12:55
mshinwell added a commit that referenced this pull request Mar 3, 2016
@mshinwell mshinwell merged commit 8a4b0c9 into ocaml:4.03 Mar 3, 2016
mshinwell added a commit that referenced this pull request Mar 3, 2016
@trefis trefis deleted the 4.03-docstrings branch March 7, 2016 12:02
Gbury pushed a commit to Gbury/ocaml that referenced this pull request Jun 21, 2021
Gbury pushed a commit to Gbury/ocaml that referenced this pull request Jun 22, 2021
EmileTrotignon pushed a commit to EmileTrotignon/ocaml that referenced this pull request Jan 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants