Introduce text checks (vale.sh) on Docstrings and comments

[kellertuer]

This PR slowly works through all doc strings to fulfil the vale.sh rules the documentation already follows, because since the 3.0 version vale.sh works on Julia files and recognises its doc-strings.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (8851619) 99.45% compared to head (7a72d41) 99.22%.
Report is 4 commits behind head on master.

❗ Current head 7a72d41 differs from pull request most recent head 1f0180b. Consider uploading reports for the commit 1f0180b to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #353      +/-   ##
==========================================
- Coverage   99.45%   99.22%   -0.23%     
==========================================
  Files          69       69              
  Lines        6418     6194     -224     
==========================================
- Hits         6383     6146     -237     
- Misses         35       48      +13     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[kellertuer]

Vale does not yet fully work, so I do not want to activate a CI on this yet. The main challenges are

• maybe I was a bit to eager declaring strings to be vale-d as well (especially when they are formats)
• qmd files and their rendered results are not handled correctly, code in those markdown files seems to be treated as text, which of course is not what it is and complains about _ that should not be used in words or such.

Still. These first steps

• improve readability
• have a large scale change, so I do not want to keep this PR open longer.

Since this does not add new features, but just rewrites docs, this will not be a new version, but be on master until a next feature justifying a new version comes along.

[mateuszbaran]

• maybe I was a bit to eager declaring strings to be vale-d as well (especially when they are formats)
• qmd files and their rendered results are not handled correctly, code in those markdown files seems to be treated as text, which of course is not what it is and complains about _ that should not be used in words or such.

Would it be possible to enable Vale on CI only for comments but not for strings and qmd files?

BTW, I most likely won't look over all these changes so merge when you think it's ready.

[kellertuer]

Sure it is a lot of changes, no worries – and most of them are even mainly unifying formatting of Keyword arguments and such.

For comments and not strings – in theory yes, in practice, I can not find how to do that.
For dmd files I for now deactivated that, but locally it still vales the resulting *.md files as well and I am not able to say “please do not check this folder, those are autogenerated anyways”. As far as I could read about it, vale is not meant to ignore folders by design or something.