Ignore commented out declarations

[fingolfin]

Fixes #66 and generally makes AutoDoc parsing a bit stricter.

Now that I think about it: a few people may have abused the fact that GAP parses commented out declarations... Alas, we never documented this, and I'd argue that we never should have parsed those. People who abused it this way should file issues with us telling us about their use cases, so that we can support it properly.

[fingolfin]

Being able to get rid of @DONT_SCAN_NEXT_LINE is a nice side benefit, IMHO.

[codecov]

Codecov Report

Merging #224 into master will increase coverage by 0.03%.
The diff coverage is 90.62%.

@@            Coverage Diff             @@
##           master     #224      +/-   ##
==========================================
+ Coverage   74.95%   74.98%   +0.03%     
==========================================
  Files          13       13              
  Lines        2336     2347      +11     
==========================================
+ Hits         1751     1760       +9     
- Misses        585      587       +2

Impacted Files	Coverage Δ
makedoc.g	94.73% <66.66%> (-5.27%)	⬇️
gap/Parser.gi	63.14% <93.1%> (+0.32%)	⬆️

[codecov]

Codecov Report

❌ Patch coverage is 90.62500% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.98%. Comparing base (5d35e72) to head (79f6397).
⚠️ Report is 116 commits behind head on master.

Files with missing lines	Patch %	Lines
gap/Parser.gi	93.10%	2 Missing ⚠️
makedoc.g	66.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #224      +/-   ##
==========================================
+ Coverage   74.95%   74.98%   +0.03%     
==========================================
  Files          13       13              
  Lines        2336     2347      +11     
==========================================
+ Hits         1751     1760       +9     
- Misses        585      587       +2     

Files with missing lines	Coverage Δ
makedoc.g	94.73% <66.66%> (-5.27%)	⬇️
gap/Parser.gi	63.14% <93.10%> (+0.32%)	⬆️

🚀 New features to boost your workflow:

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

[zickgraf]

We use the fact that commented operations are parsed to add documentation for operations which are already installed for more general filters, see e.g. https://github.com/homalg-project/FinSetsForCAP/blob/25c0b9b02752de6d468d19fd79d2d13e16dbb41d/gap/FinSetsForCAP.gd#L120

It would be nice to have a replacement for this.

[fingolfin]

Since people are using this, this PR can't be merged as-is. I propose the following strategy:

1. Add an alternative mechanism for adding ManSections without following DeclareFOOBAR commands. E.g. by adding a @ManSection TYPE NAME command, used as @ManSection Prop IsFOO; other suggestions are also welcome!
2. Add code which detects when AutoDoc "sees" a commented out operation/property/... as in #DeclareProperty("IsFoo", IsBar); and documents it. Then have it print out a deprecation warning.
3. Make an AutoDoc release with those two, and wait. Optionally, also run as many packages makedoc.g file and watch for the deprecation warning, then submit issues / PRs to any affected packages
4. Once all packages switch to the new approach, we can finally remove support for this mis-feature, i.e., merge this PR in its current form.

[zickgraf]

I have two other ideas for an alternative mechanism (I'm not suggesting they are better than you're approach, just two random ideas):

1. Do not parse DeclareProperty after a regular comment #, but parse it after an AutoDoc comment #!.
2. Introduce @DeclareProperty which is parsed exactly as DeclareProperty and can be used in comments.

[stertooy]

With the recent (amazing!) updates to AutoDoc by @fingolfin, perhaps now is a good time to revive this discussion?

My current use cases for commenting out declarations are:

1. As a workaround to document functions declared using DeclareSynonym, e.g.

   #! @Arguments hom1[, hom2], g
   # DeclareGlobalFunction( "ReidemeisterClass" );
   #
   DeclareSynonym( "ReidemeisterClass", TwistedConjugacyClass );
   

   That'll no longer be necessary thanks to Support documenting DeclareSynonym and DeclareSynonymAttr #349.

2. To document the usage of existing global functions in a new context, e.g. being able to apply Intersection or List to objects defined by the package. If not commented out, we get

   gap> DeclareGlobalFunction( "Intersection" );
   Error, BIND_GLOBAL: variable `Intersection' must be unbound
   

   A workaround that doesn't involve using comments, possibile thanks to Add @ItemType for InstallMethod docs #342 and Allow documenting function via comment on DeclareGlobalName #343, is using DeclareGlobalName for the declaration and annotating with @Arguments and/or @ItemType. E.g.

   #! @Arguments C1, C2, ...
   DeclareGlobalName( "Intersection" );
   

I still think it would be nice to have an AutoDoc-command for documenting something without having to actually pass a declaration to GAP, though. With regards to the current suggestions:

• @ManSection TYPE NAME as proposed by @fingolfin: I suppose TYPE can now be omitted and provided using @ItemType instead. The one downside I see is that this cannot create auto-generated labels in the same way DeclareOperation etc. would?

• @DeclareProperty (and variants, I assume) as proposed by @zickgraf: I quite like this, especially since this could deal with the item types and auto-generated labels. But implementation-wise, it might be quite a bit of work to provide an AutoDoc variant of every Declare...-command?