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
Consistently use @raise tags in Stdlib docs #8644
Conversation
I like the conversion to I'm less thrilled about the necessity of reformatting double-spaces and exactly where |
Use of @raise tags when it was in text. for list.mli file. Like asked by @dra27 in ocaml#8644
I have not modified double space in list.mli and change where |
Please don't; the string payload of Invalid_argument occasionally changes, and it's a bad idea for users to rely on it. |
Please do try to test these - |
I leave it to @gasche to rule whether the whitespace alterations in It's entirely up to you, @Et7f3, but a quick grep reveals arrayLabels.mli, array.mli, bigarray.mli, buffer.mli, bytesLabels.mli, bytes.mli, camlinternalFormat.ml, char.mli, digest.mli, filename.mli, float.mli, gc.mli, int32.mli, int64.mli, nativeint.mli, queue.mli, scanf.mli, stack.mli, stdlib.mli, stringLabels.mli, string.mli, sys.mli and weak.mli also contain "Raise", if you fancied changing some more. A further improvement which could be applied here and more widely would be to remove the arguments in documentation comments from |
The modules CamlinternalFormat have a manual page and comment but comment is not displayed. Is it intended ? Or we should transform comment to ocamldoc format ? How should I treat |
Unfortunately, I don't have the time right now to review this properly. @dra27, if you do have the time at some point, I would be happy to defer all decisions to you. |
Use of @raise tags when it was in text. for list.mli file. Like asked by @dra27 in ocaml#8644
@dra27 the whitespace changes shouldn't prevent us from merging this.
|
Use of @raise tags when it was in text. for list.mli file. Like asked by @dra27 in ocaml#8644
Use of @raise tags when it was in text. for list.mli file. Like asked by @dra27 in ocaml#8644
Use of @raise tags when it was in text. for list.mli file. Like asked by @dra27 in ocaml#8644
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There are four instances of Failure
and Invalid_argument
still with an argument (I don't think ocamldoc renders @raise Exception ["argument"]
very nicely, though I haven't actually checked).
I'm happy for this to go in without a Changes entry, unless you want to push one (potentially with those four adjustments) and then I'll (finally) merge this, thanks!
All comment have the same shape `(** comment *)` Use of @raise tags when it was in text. Do you think it worth ask for ocamldoc autodetect exception and try to detect which value cause error (by scanning code like if match ... with structure ?)
Use of @raise tags when it was in text. for list.mli file. Like asked by @dra27 in ocaml#8644
Co-authored-by: David Allsopp <david.allsopp@metastack.com>
My sed.js used:
I launched with: (I haven't used ocaml stdlib because I think the nodejs has more utility function and I feel dumb to have beginned this task by hand 🤡) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice! Two small nits remain. The use of 3 spaces before @raise
means that the source-formatting is off in many places. It won't affect the HTML, but if you're doing it all with a script why not:
- Preprocess by hand the small number of places where
Raise
does not begin on a newline - Capture the
\s
in the regexp and use the capture group for the spacing instead of a hard-coded 3 spaces?
Co-authored-by: David Allsopp <david.allsopp@metastack.com>
Does I modify failwith description or it is obvious ? |
In many files 2/3 or 3/4 spaces are used.
sometime we have
I have fixed by hand. |
What I meant with the pre-processing is that if you ensure by hand that "Raise" is always on a newline then you won't have any cases of "text Raise" |
I don't understand - where? |
Oh, do you mean the description of |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a really nice set of changes! I went through everything one last time - there are the last few smallest nits (and, as there were some, there is a typo which I spotted but which was nothing to do with the change)
This feels highly worth of a Changes entry, if you want to add an entry in the Changes
file in the Standard Library
section? I'm happy to rebase this on to 4.11, so it can go in the Standard Library
section of the 4.11 changes.
I have already rebased onto trunk. |
Please feel very welcome to do a follow-up PR, although this one is now quite large and I'd prefer not to have to read them all again!
That's correct - this will be merged to trunk, I was talking cherry-pick it all for OCaml 4.11 (i.e. don't worry!) |
Co-authored-by: David Allsopp <david.allsopp@metastack.com>
Only read the two last commit (I just moved two lines in the last commit) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sorry - I ran the diff through the patdiff
tool which has better context display than GitHub. I promise this is the last tranche!
Co-authored-by: David Allsopp <david.allsopp@metastack.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've checked through the HTML output as well - this is a very nice set of updates to the standard library documentation, thank you!
(cherry picked from commit c4851b0)
All comment have the same shape
(** comment *)
Use of @raise tags when it was in text.
Do you think it worth ask for ocamldoc autodetect exception and try to detect which value cause error (by scanning code like if match ... with structure ?)