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

Sys_error documentation #3468

Closed
vicuna opened this issue Feb 15, 2005 · 3 comments
Closed

Sys_error documentation #3468

vicuna opened this issue Feb 15, 2005 · 3 comments

Comments

@vicuna
Copy link

vicuna commented Feb 15, 2005

Original bug ID: 3468
Reporter: administrator
Status: acknowledged
Resolution: open
Priority: normal
Severity: minor
Category: documentation

Bug description

Full_Name: Didier Remy
Version: 3.08
OS:
Submission from: quincy.inria.fr (128.93.8.52)

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]

    http://caml.inria.fr/ocaml/htmlman/libref/index_exceptions.html

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.

Amicalement,

    Didier
@vicuna
Copy link
Author

vicuna commented Jul 24, 2013

Comment author: @damiendoligez

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.

@vicuna
Copy link
Author

vicuna commented May 25, 2017

Comment author: @yallop

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 Pervasives.int, for an identifier.

Are there technical obstacles to extending Pervasives in this way?

@github-actions
Copy link

This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc.

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