Add signatures to docstring examples in the manual

[nalimilan]

These examples did not follow the guidelines given in the rest
of the page. Also mark a few code blocks as being Julia code.

[tkelman]

4 space indent these bodies while at it?

[nalimilan]

Done.

[Sacha0]

Perhaps retain one example of the single-line "... docstring here..." syntax? Best!

[nalimilan]

Perhaps retain one example of the single-line "... docstring here..." syntax? Best!

What for? We don't recommend it, so it sounds confusing to show it in the manual. I guess we will add an example of it when it will be possible to document a type's field (that DocStringExtensions currently supports).

[Sacha0]

What for? We don't recommend it

It is useful? (For example for compact internal documentation?) Why do we not recommend it? Thanks!

[nalimilan]

Not sure. Indeed it can be used for internal documentation, but if you add internal docstrings why not add the signature while you're at it?

[Sacha0]

why not add the signature while you're at it?

I use " ... " only when I expect the docstring will (primarily) be read alongside the code, for example in place of a single-line comment describing a magical underscore method. In that case duplicating the signature in the docstring seems unnecessary and expands the code by at least a few lines.

Perhaps I should just use a single-line comment instead? Please let me know if so, and kindly ignore this suggestion. Thanks!

[MichaelHatherly]

We don't really need handwritten signatures above every docstring now that we don't use genstdlib.jl; that was just a requirement for how it worked.

It is usually useful to have a signature, but there are cases, such as minor internal docs (as mentioned here) and docs that have a really straight forward signature (such as constants) that don't really need them. (Probably worth revisiting the guidelines once everyone has had one some to get used to the new system.)

[nalimilan]

Fair enough. I've kept the first one-liner. The confusion which prompted this PR was about the second example anyway, and the guidelines advise explicitly to always include the signature.