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

Use the tag @since provided by ocamldoc #4831

Closed
vicuna opened this issue Jun 30, 2009 · 6 comments
Closed

Use the tag @since provided by ocamldoc #4831

vicuna opened this issue Jun 30, 2009 · 6 comments

Comments

@vicuna
Copy link

vicuna commented Jun 30, 2009

Original bug ID: 4831
Reporter: Julien Signoles
Assigned to: @zoggy
Status: closed (set by @zoggy on 2010-05-31T11:53:36Z)
Resolution: fixed
Priority: normal
Severity: feature
Fixed in version: 3.12.0+dev
Category: documentation
Monitored by: @ygrek

Bug description

It 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.

@vicuna
Copy link
Author

vicuna commented Apr 22, 2010

Comment author: Julien Signoles

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 *)

@vicuna
Copy link
Author

vicuna commented May 21, 2010

Comment author: @damiendoligez

I think @Changed would be better than @modify.

@vicuna
Copy link
Author

vicuna commented May 21, 2010

Comment author: @zoggy

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).

@vicuna
Copy link
Author

vicuna commented May 21, 2010

Comment author: Julien Signoles

I agree with your proposal.

@vicuna
Copy link
Author

vicuna commented May 21, 2010

Comment author: @damiendoligez

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.

@vicuna
Copy link
Author

vicuna commented May 31, 2010

Comment author: @zoggy

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant