Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0006916OCamllexing and parsingpublic2015-06-25 03:592018-07-15 06:42
Reporterygrek 
Assigned To 
PrioritynormalSeveritytweakReproducibilityalways
StatusresolvedResolutionwon't fix 
PlatformOSOS Version
Product Version4.02.2 
Target VersionlaterFixed in Version 
Summary0006916: warning 50 (documentation comments) too strict
DescriptionNew 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?
TagsNo tags attached.
Attached Files

- Relationships

-  Notes
(0014150)
lpw25 (developer)
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 (reporter)
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 (developer)
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 (administrator)
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 (reporter)
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 (developer)
2015-08-27 16:47
edited on: 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.


- Issue History
Date Modified Username Field Change
2015-06-25 03:59 ygrek New Issue
2015-06-25 11:49 lpw25 Note Added: 0014150
2015-06-25 23:10 ygrek Note Added: 0014152
2015-06-25 23:14 doligez Status new => feedback
2015-06-25 23:14 doligez Product Version => 4.02.2
2015-06-26 10:40 lpw25 Note Added: 0014154
2015-07-22 16:35 doligez Note Added: 0014240
2015-07-22 16:35 doligez Target Version => 4.03.0+dev / +beta1
2015-08-27 16:37 oandrieu Note Added: 0014412
2015-08-27 16:47 lpw25 Note Added: 0014413
2015-08-27 16:47 lpw25 Note Edited: 0014413 View Revisions
2015-08-27 16:47 lpw25 Note Edited: 0014413 View Revisions
2016-04-15 16:37 doligez Target Version 4.03.0+dev / +beta1 => later
2017-02-23 16:36 doligez Category OCaml general => -OCaml general
2017-02-24 13:13 doligez Severity minor => tweak
2017-02-24 13:13 doligez Status feedback => resolved
2017-02-24 13:13 doligez Resolution open => won't fix
2017-02-24 13:13 doligez Category -OCaml general => lexing and parsing
2018-07-15 06:42 user11136 Note Added: 0019243
2018-07-15 09:55 gasche Note Deleted: 0019243


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker