Tweak some docstrings

[fingolfin]

Partially inspired by https://github.com/tecosaur/CheckDoc.jl feedback.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.51%. Comparing base (ad61fb1) to head (eae1036).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1286   +/-   ##
=======================================
  Coverage   76.51%   76.51%           
=======================================
  Files          61       61           
  Lines        4910     4910           
=======================================
  Hits         3757     3757           
  Misses       1153     1153           

Files with missing lines	Coverage Δ
src/GAP.jl	91.86% <ø> (ø)
src/gap_to_julia.jl	97.59% <ø> (ø)
src/help.jl	73.91% <ø> (ø)
src/julia_to_gap.jl	97.32% <ø> (ø)
src/packages.jl	50.64% <ø> (ø)
src/utils.jl	65.85% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[fingolfin]

The "Test GAP packages distro" failures (were tests just hang and are cancelled after 20 minutes) are puzzling, but don't seem to be related to this patch: they also occur on master. And it is always the same 11 packages, so not purely random. But I can't really spot a pattern in that list of packages ?!?

• corefreesub
• cubefree
• lins
• grpconst
• majoranalgebras
• orb
• recog
• smallclassnr
• twistedconjugacy
• utils
• xmodalg

Looking at the CI history logs, it seems that this started between November 14 (last "good" build) and November 17 (first "bad" build). What could have changed in that time, though? The various GAP*_jll did not get an update in that time, did they?

Any ideas, @lgoettgens @ThomasBreuer ?

[fingolfin]

Argh wait, now it works on this PR after restarting it one more time??? That's a weird coincidence (but I'll take it)

[lgoettgens]

Argh wait, now it works on this PR after restarting it one more time??? That's a weird coincidence (but I'll take it)

My best guess is that this was some weird interaction of the cloudflare issues last week, together with some caching in github actions.
If you encounter this again, please let me know and I'll have a look then

[lgoettgens]

The kwarg was not part of the public API until this PR. I just wanted to mention it, so that it can be a conscious decision. No objection from my side

[fingolfin]

I've removed this part then so we can discuss it another time. Also it would conflict with PR #1300