Mantis Bug Tracker
Main | My View | View Issues | Change Log | Roadmap
  

View Issue Details [ Jump to Notes ] [ Issue History ] [ Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0004831OCamlOCaml documentationpublic2009-06-30 09:462012-07-16 14:41
ReporterJulien Signoles 
Assigned Toguesdon 
PrioritynormalSeverityfeatureReproducibilityN/A
StatusclosedResolutionfixed 
PlatformOSOS Version
Product Version 
Target VersionFixed in Version3.12.0+dev 
Summary0004831: Use the tag @since provided by ocamldoc
DescriptionIt would be great if the documentation of the ocaml stdlib uses the ocamldoc tag @since in order to know when an element was introduced. Without this information, it is very hard for a library provider to preserve the compatibility with an old ocaml version: remember yourself when any recent feature was introduced is quite impossible.
TagsNo tags attached.
Attached Files

- Relationships

-  Notes
(0005361)
Julien Signoles (reporter)
2010-04-22 13:52

 In the same way an ocamldoc tag "@modify text" indicating the version number which introduces a backward incompatiblity for an API function would be great.

For instance:
pervasives.mli:
val int_of_string:
(** Convert the given string to an integer.
   The string is read in decimal (by default) or in hexadecimal (if it
   begins with [0x] or [0X]), octal (if it begins with [0o] or [0O]),
   or binary (if it begins with [0b] or [0B]).
   Raise [Failure "int_of_string"] if the given string is not
   a valid representation of an integer, or if the integer represented
   exceeds the range of integers representable in type [int].
    @modify 3.12.0
    @modify 3.08.0 *)
(0005485)
doligez (manager)
2010-05-21 14:08

 I think @changed would be better than @modify.
(0005489)
guesdon (manager)
2010-05-21 17:41

 I think additional info should be provided about the change, for example
(**
  Convert ....
  @changed 3.12.0 Invalid_argument instead of Failure was raised before.
  @changed 3.08.0 No exception was raised before.
*)

Well, shouldn't this tag be @before instead of @changed ? :
(**
  Convert ....
  @before 3.12.0 Invalid_argument instead of Failure was raised.
  @before 3.08.0 No exception was raised.
*)
In my opinion, it seems easier to read (and to write).
(0005490)
Julien Signoles (reporter)
2010-05-21 17:45

 I agree with your proposal.
(0005491)
doligez (manager)
2010-05-21 20:31
edited on: 2010-05-21 20:32

 I have annotated the standard library. Anything that is not marked is unchanged since 3.08.0 or before.

Leaving this PR open for the @before tag to be implemented in ocamldoc.
(0005535)
guesdon (manager)
2010-05-31 13:53

 Handling of @before tags in ocamldoc is implemented in revision 10480.

- Issue History
Date Modified Username Field Change
2009-06-30 09:46 Julien Signoles New Issue
2010-04-22 13:52 Julien Signoles Note Added: 0005361
2010-05-21 14:08 doligez Note Added: 0005485
2010-05-21 16:54 doligez Status new => assigned
2010-05-21 16:54 doligez Assigned To => doligez
2010-05-21 17:41 guesdon Note Added: 0005489
2010-05-21 17:45 Julien Signoles Note Added: 0005490
2010-05-21 19:03 doligez Target Version => 3.12.0+dev
2010-05-21 20:31 doligez Note Added: 0005491
2010-05-21 20:32 doligez Assigned To doligez => guesdon
2010-05-21 20:32 doligez Resolution open => reopened
2010-05-21 20:32 doligez Fixed in Version => 3.12.0+dev
2010-05-21 20:32 doligez Note Edited: 0005491
2010-05-31 13:53 guesdon Note Added: 0005535
2010-05-31 13:53 guesdon Status assigned => closed
2010-05-31 13:53 guesdon Resolution reopened => fixed
2012-07-16 14:41 doligez Target Version 3.12.0+dev =>

Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker