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

docstrings #477

Merged
merged 4 commits into from Mar 3, 2016

Conversation

Projects
None yet
4 participants
@trefis
Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor

commented Feb 24, 2016

Apparently @damiendoligez has said this would go in 4.03

@mshinwell mshinwell added this to the 4.03.0 milestone Feb 24, 2016

@trefis trefis force-pushed the trefis:4.03-docstrings branch from 3cac9d4 to 340413f Feb 29, 2016

@trefis

This comment has been minimized.

Copy link
Contributor Author

commented Feb 29, 2016

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

  • backtraces stuff in the flambda case, which is unrelated to the feature (cf. #481 (comment) )
  • camlp4 version problem which wasn't present before the rebase and is most likely unrelated
@trefis

This comment has been minimized.

Copy link
Contributor Author

commented Feb 29, 2016

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

@trefis trefis force-pushed the trefis:4.03-docstrings branch from 340413f to 6f550f5 Feb 29, 2016

@mshinwell

This comment has been minimized.

Copy link
Contributor

commented Mar 3, 2016

@damiendoligez Is this ok to merge?

@damiendoligez

This comment has been minimized.

Copy link
Member

commented Mar 3, 2016

Yes, OK to merge.

@damiendoligez damiendoligez referenced this pull request Mar 3, 2016

Merged

Attr class 4.03 #487

@trefis trefis force-pushed the trefis:4.03-docstrings branch from 6f550f5 to 3fee64a Mar 3, 2016

mshinwell added a commit that referenced this pull request Mar 3, 2016

@mshinwell mshinwell merged commit 8a4b0c9 into ocaml:4.03 Mar 3, 2016

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

mshinwell added a commit that referenced this pull request Mar 3, 2016

@trefis trefis deleted the trefis:4.03-docstrings branch Mar 7, 2016

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