MantisBT - OCaml
View Issue Details
0006916OCamllexing and parsingpublic2015-06-25 03:592018-07-15 06:42
ygrek 
 
normaltweakalways
resolvedwon't fix 
4.02.2 
later 
0006916: warning 50 (documentation comments) too strict
New warning in 4.02.2 leads to less compact code.

Consider:

type t1 = {
  a:int; (** a *)
  b:int; (** b *)
}

type t2 = <
  a:int; (** a *)
  b:int; (** b *)
>

module type T = sig
val a : unit -> int (** a *)
val b : unit -> int (** b *)
end

This results in

File "a.ml", line 7, characters 9-17:
Warning 50: unattached documentation comment (ignored)
File "a.ml", line 8, characters 9-17:
Warning 50: unattached documentation comment (ignored)
File "a.ml", line 12, characters 20-28:
Warning 50: ambiguous documentation comment

So for the records tail-placement of comments is ok, but not for objects nor module types. Can it be fixed so that all these examples be accepted?
No tags attached.
Issue History
2015-06-25 03:59ygrekNew Issue
2015-06-25 11:49lpw25Note Added: 0014150
2015-06-25 23:10ygrekNote Added: 0014152
2015-06-25 23:14doligezStatusnew => feedback
2015-06-25 23:14doligezProduct Version => 4.02.2
2015-06-26 10:40lpw25Note Added: 0014154
2015-07-22 16:35doligezNote Added: 0014240
2015-07-22 16:35doligezTarget Version => 4.03.0+dev / +beta1
2015-08-27 16:37oandrieuNote Added: 0014412
2015-08-27 16:47lpw25Note Added: 0014413
2015-08-27 16:47lpw25Note Edited: 0014413bug_revision_view_page.php?bugnote_id=14413#r2105
2015-08-27 16:47lpw25Note Edited: 0014413bug_revision_view_page.php?bugnote_id=14413#r2106
2016-04-15 16:37doligezTarget Version4.03.0+dev / +beta1 => later
2017-02-23 16:36doligezCategoryOCaml general => -OCaml general
2017-02-24 13:13doligezSeverityminor => tweak
2017-02-24 13:13doligezStatusfeedback => resolved
2017-02-24 13:13doligezResolutionopen => won't fix
2017-02-24 13:13doligezCategory-OCaml general => lexing and parsing
2018-07-15 06:42user11136Note Added: 0019243
2018-07-15 09:55gascheNote Deleted: 0019243

Notes
(0014150)
lpw25   
2015-06-25 11:49   
This is the intended behaviour.

Firstly, documentation comments on the methods of object types are not supported (and were not supported by ocamldoc). Comments can be added to object definitions, classes and class types, but not to object types.

The comment attachment rules are indeed different for sub-items (i.e. record fields and variant constructors) and items (i.e. everything else). For sub-items comments must appear after the sub-item and so there is no potential for ambiguity. For items comments may come before or after the item so blank lines are required to avoid ambiguity.

In your signature example, it is not clear that (** a *) should be attached to a rather than b, so a blank line is required after the comment to remove this ambiguity.
(0014152)
ygrek   
2015-06-25 23:10   
> Firstly, documentation comments on the methods of object types are not supported (and were not supported by ocamldoc).

This is what I get in ocamldoc 4.02.2 html output, just as expected :

type t1 = { a : int; (* a *)
      b : int; (* b *)

 }
type t2 = < a : int; (* a *)
      b : int; (* b *)

 >

As for the anbiguous comments, why doesn't compiler use same disambiguation rules as ocamldoc? Otherwise I would expect warning 50 to be split in two, so that it is possible to silence ambiguous warning, but continue get warnings on unattached comments. The latter one is useful, but the first one is compiler telling how to indent code - too invasive.
(0014154)
lpw25   
2015-06-26 10:40   
> This is what I get in ocamldoc 4.02.2 html output, just as expected

Sorry yes, I was thinking of polymorphic variants. However, ocamldoc's behaviour here is inconsistent and object types are deliberately not handled by the ocamlc parser.

> As for the anbiguous comments, why doesn't compiler use same disambiguation rules as ocamldoc?

There were a lot of complaints that ocamldoc's comment attachment rules are too complicated. The attachment rules implemented in the ocamlc parser are mostly backwards compatible but they have been slightly simplified and made more consistent.

> Otherwise I would expect warning 50 to be split in two, so that it is possible to silence ambiguous warning, but continue get warnings on unattached comments.

The support for attaching comments to the AST in the ocamlc parser is not for ocamldoc. It is so that new documentation tools can be developed which operate on .cmt(i) files. If you do not intend to use these tools you should leave warning 50 turned off. If you do intend to use them then both ambiguous comments and unattached comments should be fixed as they will not produce the expected behaviour from these tools. So I do not see the benefit of producing separate warnings.

> The latter one is useful, but the first one is compiler telling how to indent code - too invasive.

ocamldoc's comment attachment rules have always been sensitive to blank lines, this is just another instance of that. If you do not like blank-line sensitivity you can instead use attributes. The ocamlc parser produces the same output for:

  module type T = sig
    val a : unit -> int (** a *)

    val b : unit -> int (** b *)
  end

and

  module type T = sig
    val a : unit -> int [@@doc "a"]
    val b : unit -> int [@@doc "b"]
  end

(Again this only applies to tools based on the new support for attaching comments in the ocamlc parser. It does not apply to ocamldoc).
(0014240)
doligez   
2015-07-22 16:35   
Nitpick:

    val a : unit -> int [@@doc "a"]

If you really want the same output from the compiler, this should be [@@ocaml.doc "a"]. But the tools will treat @@doc in the same way as @@ocaml.doc, so they are equivalent.
(0014412)
oandrieu   
2015-08-27 16:37   
>> As for the anbiguous comments, why doesn't compiler use same disambiguation rules as ocamldoc?

>There were a lot of complaints that ocamldoc's comment attachment rules are too complicated. The attachment rules implemented in the ocamlc parser are mostly backwards compatible but they have been slightly simplified and made more consistent.

Not a big fan either of these new rules for attaching comments …

Rules for ocamldoc in .ml files were pretty straightforward IMHO (comment before the element, except for records and variants).

Now in my case I have zillions of warning 50 and confusing ocaml.doc attributes because code like this:
(** comment 1 *)
let f x = ...
(** comment 2 *)
let g x = ...

results in f having both comments.

(But I agree the rules for .mli files were indeed a bit baroque).
(0014413)
lpw25   
2015-08-27 16:47   
> Now in my case I have zillions of warning 50 and confusing ocaml.doc attributes > because code like this:
> (** comment 1 *)
> let f x = ...
> (** comment 2 *)
> let g x = ...
>
> results in f having both comments.

I agree that the case for .ml files is less ambiguous because almost no one would try to put the comment for a `let` after it. However, I think that it is worth the mild inconvenience of adding a newline in order to keep the rules the same for all definitions.