Applies fixes for Doc Parser.

[BinarySoftware]

Pull Request Description

This PR bumps scala parser version to include latest commit to parser from engine repository, which fixes documentation tags, adds new tags according to specs as well as adds some of unavailable character, so that every doc in stdlib parses.

Important Notes

This PR wont solve issue with indent in first line, it will be fixed after updating AST.

Checklist

Please include the following checklist in your PR:

• The documentation has been updated if necessary.
• All code conforms to the Rust style guide.
• All code has automatic tests where possible.
• All code has been profiled where possible.
• All code has been manually tested in the IDE.
• All code has been manually tested in the "debug/interface" scene.
• All code has been manually tested by the PR owner against our test scenarios.
• All code has been manually tested by at least one reviewer against our test scenarios.

[farmaazon]

I see issues in some docs:

1. A dot in a new line.
   
2. One word became an example:
   

Are they a bugs in a docstrings, or in doc parser?

[wdanilo]

With this (lack of) description I completely do not understand. what this PR really does.

[BinarySoftware]

I see issues in some docs:

1. A dot in a new line.
   
2. One word became an example:
   

Are they a bugs in a docstrings, or in doc parser?

Hey Adam, those are bugs that i simply cant fix right now, as easily as i've fixed the tags or unavailable chars.

[BinarySoftware]

With this (lack of) description I completely do not understand. what this PR really does.

Updated.

[wdanilo]

Maciek, I asked you on Discord to create missing issues and link them here as a reply to Adam, it is not done yet, so I'm requesting changes.

[BinarySoftware]

Maciek, I asked you on Discord to create missing issues and link them here as a reply to Adam, it is not done yet, so I'm requesting changes.

Sorry for not doing that, here it comes:

enso-org/enso#1441

[farmaazon]

I see still one not-working case in the workaround provided by this PR:

## A function foo doing foo like this:
       foo

Here the doc writer meant the second line to be intended, but we align the first line to the second.

I could accept this PR, as it is not a regression, but first confirm with @wdanilo that fixing that properly in the parser is impossible or too costly.

[farmaazon]

Please extend this description. What does "looking at next line" mean? Do we adjust the first line to the second? What if there is only one line? What if documentation author meant the second line to be indented?

If we really need to put a workaround here (not in parser), then I'd rather put three spaces to the first line (an equivalent of ## . Or maybe shall we put two spaces for ## instead? I'm not sure, I don't know how parser works).

[BinarySoftware]

no, putting fixed amount of spaces wont fix the issue.
Take a look at some enso code:

type foo
    type bar
        ## docs here
           docs there
        type baz

We need to add the indentation of whole block plus the indent of 2 hashes - that is in this case 10 additional spaces, otherwise doc parser will get code like this:

 docs here
          docs there

and will create a synopsis with raw text "docs here" and code block of "docs there".

As we talked on dm, if there is only one line, there is no problem, it just wont do anything, and will work. If the next line is empty, there is still no problem, as what is in the next box will just become new paragraph, just as intended, in "body" section.

The only corner case is when the user specifically intends to make second line a code block, but that must be a really rare case, as i havent seen such in any doc in stdlib.

To sum up, this thing is really not a trivial fix as the doc code we get doesnt know anything about its origin, what was its indentation etc, hence the need to write such a hack. To be further discussed with @wdanilo but I dont see any other reasonable solution currently.

[BinarySoftware]

After talk I've removed hack method, this PR wont fix indent in first line.

[farmaazon]

Please fix a changelog entry before merge. I would rather not mention that our fixes are "hot".

[wdanilo]

the changelog entries should be understandable to the end-users. Not all are perfect now, but this description "fixing documentation layout in Searcher" is not very understandable. Also, "fixing" means that it is being done, not done already, so its not a good form for a changelog. Can we describe here what was fixed and what kind of docs will be displayed better now ?