Add many "see also" links to docstrings#38606
Conversation
|
CI doesn't like this, I'm not sure why. Is there a trick needed for these? |
|
Possibly not the canonical name for it? Often they are |
|
Alternatively they are not included in the manual. For example |
|
Thanks for the hints. I'm slowly ironing them out locally, a few more builds to go. |
|
I couldn't make a reference to Questions:
|
|
It would be great to get this in. |
|
Excellent, what needs to happen, do you think?
|
|
I would think that the newly documented ones should be in a separate PR than the cross-links. That might perhaps make it easier to get things merged rather than all in one shot. I wonder what others have to say about that. |
|
I don't mind moving them, although note that the two PRs will still be coupled, in the sense that links here won't work until their targets exist. The advantage of reviewing them in here is that you can easily search for the (proposed) links toward a given function. (They should all be gathered about here on the super-long "files changed" page.) They are just things (like |
|
Makes sense. |
|
Some comments of places to fix, but otherwise, lgtm |
Co-authored-by: Jameson Nash <vtjnash@gmail.com>
Co-authored-by: Jameson Nash <vtjnash@gmail.com>
vtjnash
left a comment
There was a problem hiding this comment.
A couple nits, and we should merge this
Co-authored-by: Jameson Nash <vtjnash@gmail.com>
base/irrationals.jl
Outdated
|
|
||
| """ | ||
| Irrational{sym} <: AbstractIrrational | ||
| `Irrational{sym}` <: [`AbstractIrrational`](@ref) |
There was a problem hiding this comment.
oh, I didn't necessarily mean we should do this now. I'm probably in favor, but we should let others respond first in a separate PR
There was a problem hiding this comment.
Sorry, now reverted.
Possibly it could be done at a higher level, too, just make all types in docstrings clickable somehow?
This adds many more cross-links to the functions' docstrings. They are a little random, but the goal is to link to a few similar or contrasting functions whose existence, or precise names, might not be known.
They are mostly above
# Examplesas this seemed to be the policy. Although perhaps if the lists get longer, they ought to move to below.I also edited a few other docstrings, including:
floatmaxandtypemaxunder each other's headings,showingsimilarunderArray{T}(undef, ...)collecton variousIterators.objects.Edit -- more:
mapandforeachto say "iteration stops when any iterator is finished" andmap!to say "destinationmust be at least as large as the smallest collection" not the first.&&etc.ℯ^(im)π ≈ -1to irrational constants.I also added some functions to doc pages, to have something to refer to. Not sure how big a deal this is or isn't; I don't want to accidentally make policy.