[WIP]/[RFC] Move EVEN MORE things out of helpDB #18511
Conversation
| immutable NullException <: Exception | ||
| end | ||
|
|
||
| """ | ||
| Nullable(x, isnull::Bool=false) |
There was a problem hiding this comment.
is the second argument meant to be used?
There was a problem hiding this comment.
Let's discuss this at #18510 (comment).
| error(message::AbstractString) | ||
|
|
||
| Raise an [`ErrorException`](:obj:`ErrorException`) with the given message. | ||
| """ |
There was a problem hiding this comment.
Wouldn't it be better to document the more general error(s...) below?
| """ | ||
| systemerror(sysfunc, iftrue::Bool; extrainfo=nothing) | ||
|
|
||
| Raises a `SystemError` for `errno` with the descriptive string `sysfunc` if `iftrue` is `true`. |
There was a problem hiding this comment.
This one is quite confusing. What is errno? What does extrainfo do?
| assert(cond) | ||
|
|
||
| Throw an [`AssertionError`](:obj:`AssertionError`) if `cond` is `false`. | ||
| Also available as the macro `@assert expr`. |
There was a problem hiding this comment.
Maybe we could add a ref link here to the macro?
| """ | ||
| isnull(x::Nullable) -> Bool | ||
|
|
||
| Is the [`Nullable`](:obj:`Nullable`) object `x` null, i.e. missing a value? |
There was a problem hiding this comment.
I think this would be better as a statement instead of a question.
Returns true if the ...
or something
There was a problem hiding this comment.
Or "Determine whether the Nullable object x is null, i.e. is missing."
There was a problem hiding this comment.
"Determines" (third person, as you recalled my last time :-).
EDIT: looks like that's the opposite. I can never remember this rule...
|
The docstrings need some work in general all over. For now, should we move over and merge and then tweak them? |
|
|
||
| Bessel function of the first kind of order 0, ``J_0(x)``. | ||
| """ | ||
| function besselj0(x) end |
There was a problem hiding this comment.
This will define a new method for besselj0 returning nothing which we probably don't want. Should be besselj0(x) without the function and end. Same with the other bessel* and erf* ones below.
There was a problem hiding this comment.
If I fix this up, following what @ViralBShah said, should we merge?
There was a problem hiding this comment.
I'd rather do some cleanup now while people are looking at the diff
| """ | ||
| getindex(A, inds...) | ||
|
|
||
| Returns a subset of array `A` as specified by `inds`, where each `ind` may be an |
There was a problem hiding this comment.
I think the preferred style is to describe the action in the imperative. In this case it would be "return" instead of "returns."
|
|
||
| Bessel function of the first kind of order 0, ``J_0(x)``. | ||
| """ | ||
| besselj0(x) |
There was a problem hiding this comment.
I think these should be besselj0 without the (x)
There was a problem hiding this comment.
If there's only a single docstring for besselj0 then either syntax is fine really. It'll only matter if we had several different methods of the function and we wanted to document each one separately.
| Compute the error function of `x`, defined by ``\\frac{2}{\\sqrt{\\pi}} \\int_0^x e^{-t^2} dt`` | ||
| for arbitrary complex `x`. | ||
| """ | ||
| function erf(x) end |
There was a problem hiding this comment.
Same comment as with the Bessel functions: should just be erf.
kshyatt
force-pushed
the
ksh/docamputation2
branch
from
df504ac to
e46374b
Compare
kshyatt
force-pushed
the
ksh/docamputation2
branch
from
e46374b to
4f09334
Compare
|
This is so old, and way out of date, let's start again new. |
A bunch of these docstrings are kind of confusing and I don't know the best way to reword. Feedback very welcome!