Add many "see also" links to docstrings

[mcabbott]

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 # Examples as 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:

• giving examples of floatmax and typemax under each other's headings,
• showing similar under Array{T}(undef, ...)
• mentioning that comprehensions use collect on various Iterators. objects.

Edit -- more:

• correcting map and foreach to say "iteration stops when any iterator is finished" and map! to say "destination must be at least as large as the smallest collection" not the first.
• adding examples to short-circuiting && etc.
• adding examples like ℯ^(im)π ≈ -1 to 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.

[mcabbott]

CI doesn't like this, I'm not sure why. Is there a trick needed for these?

┌ Warning: no doc found for reference '[`@info`](@ref)' in src/base/base.md.
┌ Warning: no doc found for reference '[`copy!`](@ref)' in src/base/base.md.
┌ Warning: no doc found for reference '[`⊉`](@ref)' in src/base/collections.md.

[vtjnash]

Possibly not the canonical name for it? Often they are [@ref Base.copy!] and such

[fredrikekre]

Alternatively they are not included in the manual. For example @info does not exist, it is only documented as the generic @logmsg

[mcabbott]

Thanks for the hints. I'm slowly ironing them out locally, a few more builds to go.

[mcabbott]

I couldn't make a reference to @logmsg or Logging.@logmsg, but could make a reference to Logging which might be narrow enough.

Questions:

• Can I include references from Base to functions in standard libraries somehow, or is that impossible? At the moment I just reference the library itself, or the heading of the manual section. That's more useful for @printf than for LinearAlgebra.
• Can I refer to labels like kw"?" for the ternary operator, or kw"&&", from other docstrings? I think I deleted my attempts from the present state of this.

[ViralBShah]

It would be great to get this in.

[mcabbott]

Excellent, what needs to happen, do you think?

• Some functions are newly documented, i.e. added to doc/src/base/.... Maybe that's a review priority, does this make them more official? I'm not so sure of the policy here.
• I'm still unclear how to create some cross-links, if anyone can enlighten me on Add many "see also" links to docstrings #38606 (comment) I'd appreciate it.
• More generally if anyone wants to scan a few of these and object to any (or any patterns) that would also be great, even if you don't feel like reading all of them.

[ViralBShah]

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.

[mcabbott]

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 promote_typejoin) which seemed to deserve mention from somewhere (like promote_type) and cross-links without targets don't work. I have no opinions as to whether these functions are otherwise important enough to deserve documentation. If they don't, then the options are either to remove them entirely from "See also" to keep them hidden, or to mention them without making a hyperlink.

[ViralBShah]

Makes sense.

[vtjnash]

Some comments of places to fix, but otherwise, lgtm

[vtjnash]

A couple nits, and we should merge this

[vtjnash]

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

[mcabbott]

Sorry, now reverted.

Possibly it could be done at a higher level, too, just make all types in docstrings clickable somehow?