Replaced FrobHelp with AutoDoc by AliaBonnet · Pull Request #11 · gap-packages/nofoma

AliaBonnet · 2025-10-30T13:21:38Z

FrobHelp function has been replaced by AutoDoc comments.

codecov · 2025-10-30T13:23:12Z

Codecov Report

❌ Patch coverage is 97.87234% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 88.81%. Comparing base (cbc1e6f) to head (1265af7).
⚠️ Report is 18 commits behind head on main.

Files with missing lines	Patch %	Lines
gap/nofoma.gi	94.44%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main      #11       +/-   ##
===========================================
+ Coverage   18.35%   88.81%   +70.45%     
===========================================
  Files           6        6               
  Lines         877      617      -260     
===========================================
+ Hits          161      548      +387     
+ Misses        716       69      -647

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

🚀 New features to boost your workflow:

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

fingolfin · 2025-11-25T12:47:27Z

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->


This file should not be added to the repository, no title.xml. Please remove both files from the PR (I've now updated .gitignore on main to exclude these files)

fingolfin · 2025-11-25T12:54:21Z

+#! @Description 
+#! 'GcdCoprimeSplit' computes a divisor <M>a_1</M> of the polynomial <M>a</M> and a
+#! divisor <M>b_1</M> of the polynomial <M>b</M> such that <M>a_1</M> and <M>b_1</M> are coprime
+#! and the lcm of <M>a</M>, <M>b</M> is <M>a_1</M>*<M>b_1</M>.  This is based on Lemma 5 in <Cite Key = "Bon14"/>.


There is no bibliography file in this PR and hence the Cite commands don't work and even produce an error.

Also, normally XML attributes don't use spaces around the =:

Suggested change

#! and the lcm of <M>a</M>, <M>b</M> is <M>a_1</M>*<M>b_1</M>. This is based on Lemma 5 in <Cite Key = "Bon14"/>.

#! and the lcm of <M>a</M>, <M>b</M> is <M>a_1</M>*<M>b_1</M>. This is based on Lemma 5 in <Cite Key="Bon14"/>.

fingolfin · 2025-11-25T12:55:28Z

+#! [ x^5-4*x^4+5*x^3-2*x^2,               # the (monic) gcd
+#! x^4-6*x^3+12*x^2-10*x+3,               # a1
+#! x^7-12*x^6+56*x^5-128*x^4+144*x^3-64*x^2 ]  # b1


Comments in the output make it impossible to use this example for automated testing, and also make it harder to automatically update the test output should it become necessary (e.g. because some output orders changed etc.)

Suggested change

#! [ x^5-4*x^4+5*x^3-2*x^2, # the (monic) gcd

#! x^4-6*x^3+12*x^2-10*x+3, # a1

#! x^7-12*x^6+56*x^5-128*x^4+144*x^3-64*x^2 ] # b1

#! [ x^5-4*x^4+5*x^3-2*x^2, # the (monic) gcd

#! x^4-6*x^3+12*x^2-10*x+3, # a1

#! x^7-12*x^6+56*x^5-128*x^4+144*x^3-64*x^2 ] # b1

fingolfin · 2025-11-25T12:56:30Z

+
+#! @Arguments a,b
+#! @Description 
+#! 'GcdCoprimeSplit' computes a divisor <M>a_1</M> of the polynomial <M>a</M> and a


No need to repeat the function name here, as AutoDoc automatically inserts it in the generated documentation. In fact I'd consider it an anti-pattern: if we rename a function, there is a chance we forget to adjust the documentation, and then the two diverge needlessly.

Suggested change

#! 'GcdCoprimeSplit' computes a divisor <M>a_1</M> of the polynomial <M>a</M> and a

#! Computes a divisor <M>a_1</M> of the polynomial <M>a</M> and a

fingolfin · 2025-11-25T12:57:39Z

+#! @Arguments A,pol,v
+#! @Description
+#! 'PolynomialToMatVec' returns  the row vector  obtained  by multiplying 
+#! the row vector <M>v</M> with the matrix <M>pol</M>(<M>A</M>), where <M>pol</M> is the list 


Since A, pol, v are arguments, the correct XML elements to wrap them in is <A>. So e.g.

Suggested change

#! the row vector <M>v</M> with the matrix <M>pol</M>(<M>A</M>), where <M>pol</M> is the list

#! the row vector <A>v</A> with the matrix <M><A>pol</A>(<A>A</A>)</M>, where <A>pol</A> is the list

fingolfin · 2025-11-25T12:58:21Z

+#! gap> A:=([ [ 0, 1, 0, 1 ],
+#! gap>       [ 0, 0, 0, 0 ],
+#! gap>       [ 0, 1, 0, 1 ],
+#! gap>       [ 1, 1, 1, 1 ] ]);;


Parenthesis around the matrix are unnecessary and atypical, better don't do it.

Suggested change

#! gap> A:=([ [ 0, 1, 0, 1 ],

#! gap> [ 0, 0, 0, 0 ],

#! gap> [ 0, 1, 0, 1 ],

#! gap> [ 1, 1, 1, 1 ] ]);;

#! gap> A:= [ [ 0, 1, 0, 1 ],

#! gap> [ 0, 0, 0, 0 ],

#! gap> [ 0, 1, 0, 1 ],

#! gap> [ 1, 1, 1, 1 ] ];;

fingolfin · 2025-11-25T12:59:21Z

+#!  'CyclicChainMat' repeatedly applies 'SpinMatVector1' (relative version
+#!  of 'SpinMatVector') to compute a chain of cyclic subspaces. The output
+#!  is a triple [B,C,svec]  where  C is such that  C*<M>A</M>*C^-1  has a block
+#!  triangular shape with companian matrices along the diagonal), B is the


Typo -- I suggest to run a spell checker over this document

Suggested change

#! triangular shape with companian matrices along the diagonal), B is the

#! triangular shape with companion matrices along the diagonal), B is the

fingolfin · 2025-11-25T13:00:16Z

+#! @Description
+#!  'CyclicChainMat' repeatedly applies 'SpinMatVector1' (relative version
+#!  of 'SpinMatVector') to compute a chain of cyclic subspaces. The output
+#!  is a triple [B,C,svec]  where  C is such that  C*<M>A</M>*C^-1  has a block


Suggested change

#! is a triple [B,C,svec] where C is such that C*<M>A</M>*C^-1 has a block

#! is a triple <C>[B,C,svec]</C> where <M>C</M> is such that <M>C <A>A</A> C^-1</M> has a block

fingolfin · 2025-11-25T13:00:45Z


+#! @Arguments A
+#! @Description
+#!  'CyclicChainMat' repeatedly applies 'SpinMatVector1' (relative version


Since SpinMatVector1 is not documented I would not mention it here, but rather explain what CyclicChainMat does without referring to this unknown.

fingolfin · 2025-11-25T13:01:43Z

+#! gap> A:=[ [ 0, 1, 0, 1 ],
+#! gap>      [ 0, 0, 1, 0 ],
+#! gap>      [ 0, 1, 0, 1 ],
+#! gap>      [ 1, 1, 1, 1 ] ]);;


Syntax error -- I'll make a PR to enable extraction of examples for testing, then we can see what all fails and fix these incrementally.

Suggested change

#! gap> [ 1, 1, 1, 1 ] ]);;

#! gap> [ 1, 1, 1, 1 ] ];;

fingolfin · 2025-11-25T13:03:56Z

+<Bibliography Databases="../doc/nofoma.bib"/>
+
+


This is the wrong place to put this (and in fact a syntax error).

But luckily AutoDoc automatically finds the bib if it is named PKGNAME.bib, where PKGNAME is the package name as defined in PackageInfo.g -- which here amounts to nofoma.xml. So it automatically finds the file, and you can just remove this here.

Suggested change

<Bibliography Databases="../doc/nofoma.bib"/>

… fix/issues4-9

fingolfin · 2025-11-28T20:38:28Z

This PR now does a lot more than its description suggests...

Replaced FrobHelp with AutoDoc

f0297c4

AliaBonnet added 4 commits November 12, 2025 21:56

Replaced Testnofoma, test.g, testall.g with testall.tst

ec70aa8

updated testfile in PackageInfo.g

51c2a32

Added some more comments to autodoc that were only in nofoma.gi

9bae164

Added bibliography and used it in the documentation

c6e74fd

fingolfin reviewed Nov 25, 2025

View reviewed changes

AliaBonnet added 4 commits November 26, 2025 00:20

updated gitignore

91e11a8

fixed autodoc issues

b9a02e5

removed xml files

7387e2d

Merge branch 'main' into fix/issues4-9

aed31a4

fingolfin reviewed Nov 26, 2025

View reviewed changes

Comment thread tst/tests.tst

AliaBonnet added 8 commits November 26, 2025 11:15

added doc folder including .bib file

bb3948e

added testall.g

c00dda3

Merge remote-tracking branch 'refs/remotes/origin/fix/issues4-9' into…

9426008

… fix/issues4-9

fixed test file in packageinfo

ec9a22f

added bibliography file

970de38

Updated packageinfo

99199b4

fixed packageinfo

d55886c

replaced IInofoma with Info

1265af7

AliaBonnet merged commit 5f4d0bf into main Nov 30, 2025
9 checks passed

AliaBonnet deleted the fix/issues4-9 branch November 30, 2025 14:57

		@@ -0,0 +1,17 @@
		<?xml version="1.0" encoding="UTF-8"?>

		<!-- This is an automatically generated file. -->

	#! and the lcm of <M>a</M>, <M>b</M> is <M>a_1</M>*<M>b_1</M>. This is based on Lemma 5 in <Cite Key = "Bon14"/>.
	#! and the lcm of <M>a</M>, <M>b</M> is <M>a_1</M>*<M>b_1</M>. This is based on Lemma 5 in <Cite Key="Bon14"/>.

	#! 'GcdCoprimeSplit' computes a divisor <M>a_1</M> of the polynomial <M>a</M> and a
	#! Computes a divisor <M>a_1</M> of the polynomial <M>a</M> and a

	#! the row vector <M>v</M> with the matrix <M>pol</M>(<M>A</M>), where <M>pol</M> is the list
	#! the row vector <A>v</A> with the matrix <M><A>pol</A>(<A>A</A>)</M>, where <A>pol</A> is the list

	#! triangular shape with companian matrices along the diagonal), B is the
	#! triangular shape with companion matrices along the diagonal), B is the

	#! is a triple [B,C,svec] where C is such that C<M>A</M>C^-1 has a block
	#! is a triple <C>[B,C,svec]</C> where <M>C</M> is such that <M>C <A>A</A> C^-1</M> has a block

Conversation

AliaBonnet commented Oct 30, 2025

Uh oh!

codecov Bot commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

fingolfin commented Nov 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov Bot commented Oct 30, 2025 •

edited

Loading