Improve docs for sin and some friends

[mcabbott]

Some "see also" links from #38606 were missing (@ref) and thus not really links.

Also adds a few more such links, and adds examples for sin and a few other functions.

[CameronBieganek]

Using a Float32 literal here does not seem the most beginner friendly to me. 🙂

[mcabbott]

It's mostly just a hack to avoid printing 16 digits here.

But also, strikes me as easy to ignore if you don't know, and something which you eventually should know. If you paste that bit into the REPL to see, then I guess you don't learn much:

julia> -3:3f0
-3.0f0:1.0f0:3.0f0

Maybe it could be clarified in some other way?

[CameronBieganek]

Might be better to use the explicit round broadcasting like you did for sin. Or else just live with the 16 digits of printing. Doing the rounding feels kind of like hiding the real output anyways. (Though the rounding looks good for the sin example.)

[mcabbott]

Possibly this was left off last time to avoid this error:

[ Info: CrossReferences: building cross-references.
��� Error: no doc found for reference '[`Base.@irrational`](@ref)' in src/base/numbers.md.
��� @ Documenter.CrossReferences /buildworker/worker/doctest_linux64/build/doc/deps/packages/Documenter/HmHje/src/Utilities/Utilities.jl:32
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
ERROR: LoadError: `makedocs` encountered an error. Terminating build

Should this be documented?

[CameronBieganek]

It looks like this works:

julia> for f in (:foo, :bar)
           @eval begin
               "This is the $(nameof($f)) function."
               $f(x) = 2x
           end
       end

help?> foo
search: foo floor pointer_from_objref OverflowError RoundFromZero unsafe_copyto! functionloc StackOverflowError @functionloc OutOfMemoryError

  This is the foo function.

help?> bar
search: bar baremodule SubArray GlobalRef clipboard BitArray backtrace BitMatrix catch_backtrace AbstractRange AbstractArray AbstractIrrational

  This is the bar function.

So we could use that to add foo(::Missing) docstrings for all the math functions here and here.

[mcabbott]

Maybe make an issue if you think all missing methods should be documented that way. As I said above, this seems very noisy to me, and sure to be incomplete.

[CameronBieganek]

Ok, in that case I think you should remove the Number annotation from sin(x::Number) in the docstring. If you leave that annotation there, then there are the following two docstrings for sin:

• sin(x::Number)
• sin(A::AbstractMatrix)

That implies that sin(missing) should throw a MethodError.

EDIT: Or you could change the annotation to sin(x::Union{Missing, Number}.

[KristofferC]

I think it is worth being a bit more careful about not introducing too much new vertical space unless it is really really needed. Doing ? function and then getting two pages of examples is usually kind of annoying because you have to scroll up so far to see what the function actually does. So if long examples are crucially needed to make a point about some specific behavior of the function then so be it but it should at least be given some careful thought.

[oscardssmith]

this is one of many reasons why it would be good to make help mode page.

[mcabbott]

Yes to scrolling too much being a pain.

I guess this PR is feeling the waters for making many docstrings more detailed. Inspired by this Discourse thread and one before, it seems that many people would appreciate more details, more tangentially related examples, as an informal way to learn what's possible and how to do it.

For inspiration, Mathematica's page is pretty great. That's probably impossible without a team of professionals, but small steps towards that still seem valuable. They have 2 levels of section headings (and a separate window) to avoid the scrolling problem.

Is there an issue about making help paged, like less? There is # Extended help (not exactly sure when this was added) but it doesn't seem like the ideal mechanism.

[johnmyleswhite]

To add to @mcabbott's point, it would be good to get a consistent direction for function documentation set -- will it (a) gradually expand (as many users prefer, especially new users) or (b) will it always stay as pithy as it is today? Unless there's a clear commitment to expansion soon, it may be advantageous to built an alternative documentation store for a while that either eventually gets ported over or lives forever as a separate resource. That way people can make progress without being blocked on waiting for an official strategy.

[giordano]

Would it make sense to have help mode ask for which method to show the docstring, if there is more than one (which an option to show all of them)?

[ViralBShah]

In my mind there is no doubt that we need to allow for the documentation to expand substantially, and implement whatever tooling we need in the docsystem. Until then, people just have to scroll. But keeping it short so you don't have to scroll feels wrong to me.

[mcabbott]

Do we want to do tihs?