Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0003468OCamldocumentationpublic2005-02-15 23:282017-05-25 13:09
Assigned To 
PlatformOSOS Version
Product Version 
Target VersionFixed in Version 
Summary0003468: Sys_error documentation
DescriptionFull_Name: Didier Remy
Version: 3.08
Submission from: (

Sys_error est je pense très mal documentée.
Dans Core Library, il est correctement dit:

        Exception raised by the input/output functions to report an
        operating system error.

Mais dans Pervasives, la plupart des fonctions qui peuvent la lever
(output_*, etc.) ne le disent pas. C'est d'autant plus trompeur que certaines
le disent (open_*, close_*) ce qui sugèrerait que seules celles-ci peuvent
effectivement la lever.

Par ailleurs, c'est à la limite de l'erreur de documentation de faire
[Index of exceptions] [^]

et de ne pas trouver Sys_error et toutes les autres exceptions qui sont
primitives! (Pour la même raison, on peut vérifier qu'on ne trouve pas le
type int dans index of types, etc.) J'en comprends bien la raison, mais
l'utilisateur lambda aura du mal à la comprendre... et une fois comprise à
accepter l'explication.



TagsNo tags attached.
Attached Files

- Relationships

-  Notes
doligez (administrator)
2013-07-24 11:03
edited on: 2013-07-24 11:22

This is two bug reports:

1. Inconsistent documentation of Sys_error: most of the functions from Pervasives that can raise it are not documented as such, but some are. There is now a note at the beginning of the Input/Output section that says all functions can raise Sys_error. Accordingly, I have removed the special mention of Sys_error in open_out and open_in. I left it in for close_in and close_out because it gives specific details. (branch 4.01, rev 13930)

2. All the built-in identifiers like [Sys_error] and [int] are missing from the indexes. This is harder to fix.

yallop (developer)
2017-05-25 13:09

> All the built-in identifiers like [Sys_error] and [int] are missing from the indexes. This is harder to fix.

I think it would be useful to have built-in identifiers re-exported in Pervasives

   type nonrec int = int
   exception Sys_error = Sys_error

This would improve the documentation situation for built-ins, since they'd be automatically included in the index, and it'd also help with shadowing: it's often useful (e.g. in generated code) to have a canonical top-level name, such as, for an identifier.

Are there technical obstacles to extending Pervasives in this way?

- Issue History
Date Modified Username Field Change
2005-11-18 10:14 administrator New Issue
2005-12-15 15:29 doligez Priority normal => low
2005-12-15 15:29 doligez Category OCaml general => OCaml documentation
2005-12-15 15:29 doligez Description Updated
2012-07-11 17:28 doligez Priority low => normal
2012-07-11 17:28 doligez Target Version => 4.01.0+dev
2012-07-31 13:37 doligez Target Version 4.01.0+dev => 4.00.1+dev
2012-09-11 09:44 doligez Target Version 4.00.1+dev => 4.00.2+dev
2013-07-02 14:39 doligez Target Version 4.00.2+dev => 4.01.0+dev
2013-07-24 11:03 doligez Note Added: 0009844
2013-07-24 11:13 doligez Note Edited: 0009844 View Revisions
2013-07-24 11:22 doligez Note Edited: 0009844 View Revisions
2013-07-24 11:22 doligez Target Version 4.01.0+dev => 4.01.1+dev
2014-05-25 20:20 doligez Target Version 4.01.1+dev => 4.02.0+dev
2014-08-18 18:20 doligez Target Version 4.02.0+dev => 4.02.1+dev
2014-09-04 00:25 doligez Target Version 4.02.1+dev => undecided
2014-09-18 13:32 doligez Target Version undecided => 4.03.0+dev / +beta1
2016-03-23 14:51 doligez Target Version 4.03.0+dev / +beta1 => 4.03.1+dev
2017-02-16 14:01 doligez Target Version 4.03.1+dev => undecided
2017-02-23 16:35 doligez Category OCaml documentation => Documentation
2017-02-23 16:44 doligez Category Documentation => documentation
2017-03-14 17:08 doligez Target Version undecided =>
2017-05-25 13:09 yallop Note Added: 0017814

Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker