Update user manual for scaladoc

[BarkingBad]

This PR adds:

• User manual
• Technical manual

[kitbellew]

1. i wouldn't mention wikidoc here at all, line 120 above already did.
2. could you include a link to a recent commonmark spec?

[BarkingBad]

1. The clue here is that you can write markdown code with wikidoc links, e. g. This is my *markdown* with wikidoc link to [[ my.Class ]]. If this sentence is confusing, I can elaborate.
2. Will fix

[kitbellew]

this comment seems to suggest that one must choose either markdown or the old way, not both, and the only exception is those links.

if that's not true, why do you need to call out the links specifically, if one can mix and match anything with anything?

[BarkingBad]

I'm not sure whether you talk about outdated or new version of this sentence.

As it comes to language for docstring styling, you have to choose either Wikidoc or Markdown (at least single docstring must be fully markdown or fully wikidoc), however we added extension to markdown syntax so you can use Wikidoc links while using Markdown regular elements like bold with asterisks. It is quite useful, because these links are more intelligent than regular markdown links and let you link classes etc. by their fully qualified name, so you don't have to know the absolute path of these elements.

I thought one would not be aware of this extension so this is what I meant saying Markdown uses commonmark flavour with extension of wikidoc links for referencing convenience.

[kitbellew]

that's an important observation, @BarkingBad ! i was not aware that one must choose a style for a single docstring and assumed that one can use markdown and something else mixed. can't i specify:

  /**
    * ```scala
    *    some code
    * ```
    * also
    * {{{
    *   some other code
    * }}}
    */

also, what's wikidoc? a search on google doesn't bring up any relevant results.

[BarkingBad]

Wikidoc syntax is legacy syntax used by old scaladoc. I think it's spec can be found here. The 3 curly braces was a way to declare code blocks in Scala2 (I'm not sure is it official spec or just addition by Scala2 scaladoc creators). In new Scaladoc we assume 3 curly braces syntax as part of Wikidoc and 3 backticks as Markdown.

But...

I must have missed Alekasnder's PR that implements curly braces as code blocks valid syntax even if Markdown is used. I guess I need to update the docs then.

[BarkingBad]

Hey @kitbellew @julienrf @KacperFKorban
thank you for your reviews, I hope I clarified all unclear parts. Please look at the conversations I didn't marked as resolved whether they still need work

[julienrf]

There are no package objects anymore in Scala 3? How do we document a package?

[BarkingBad]

There's an issue to deal with this problem, however many intuitive solutions require changes in sbt

[julienrf]

So, should we change/remove the part about package objects?

[BarkingBad]

This is some copy-paste leftover, I'll change it and point it to the github issue.

[julienrf]

I still have a few comments, but this is good to go.

[julienrf]

So, should we change/remove the part about package objects?

[julienrf]

I’m adding a note here to not forget to update this link after scala/docs.scala-lang#2012 is merged.

[julienrf]

Should we remove line 102?