search

gap-system / gap

Main development repository for GAP - Groups, Algorithms, Programming, a System for Computational Discrete Algebra
https://www.gap-system.org
GNU General Public License v2.0
812 stars 161 forks source link

Add more examples in the reference manual #491

Open olexandr-konovalov opened 8 years ago

olexandr-konovalov commented 8 years ago

Manual examples provide another dimension for our regression testing. They are tested by running each chapter in a fresh GAP session and are required to run exactly like they look in the manual if executed in the same order.

Some time ago I've placed a script at https://github.com/gap-system/gap/blob/master/doc/ref/testcoverage.g which checks how many ManSections in the manual do not have examples. Read it into GAP in the doc/ref directory, and it will produce a list of ManSections having no Examples, and then a summary which for the master branch as of today looks as follows:

*** TEST COVERAGE REPORT: 
2810 mansections 
1289 with examples 
1521 without examples

The actual situation is a bit better, though, since there are cases when there are separate composite examples covering several ManSections, and there are ManSections where examples does not make much sense. Still, there is a huge space for improvement here. This is a way to ensure that we exercise more of the documented functionality in addition to teststandard.g.

The full output is in the attached file noexamples.txt

olexandr-konovalov commented 8 years ago

Just to note that the functionality to check for manual sections without examples evolved and is now a part of the

make check-manuals

target which writes the report into dev/log/check_manuals_<timestamp> file.

Below is an excerpt from the report. Of course, there are cases when runnable and testable manual example does not make sense, but obviously we should not be content with having 1289 mansections with examles out of 2810. More examples will not only make the documentation better, but will also improve the code coverage (reported at http://gap-coverage.northeurope.cloudapp.azure.com/).

If you will be adding examples, please note that it is required that examples within the chapter run exactly as they look if one runs them in the same order starting GAP with the default set of packages. The best way to check this is to run make testmanuals and then inspect the deb/log/testmanualsA_<timestamp> file.

****************************************************************
*** Looking for ManSections having no examples 
****************************************************************
./help.xml:193 : SetHelpViewer
./../../lib/pager.gd:20 : Pager
./run.xml:591 : SaveWorkspace
./../../lib/system.g:503 : ARCH_IS_UNIX
./../../lib/system.g:483 : ARCH_IS_MAC_OS_X
./../../lib/system.g:465 : ARCH_IS_WINDOWS
./run.xml:631 : GAPInfo
./../../lib/colorprompt.g:34 : ColorPrompt
./../../lib/global.gd:35 : IsValidIdentifier
./language.xml:489 : IsBound
./language.xml:505 : Unbind
...
./../../lib/semigrp.gd:18 : IsSemigroup
./../../lib/semigrp.gd:111 : SemigroupByGenerators
./../../lib/semigrp.gd:129 : AsSemigroup
./../../lib/semigrp.gd:149 : AsSubsemigroup
./../../lib/monoid.gd:19 : IsMonoid
./../../lib/monoid.gd:39 : Monoid
./../../lib/monoid.gd:75 : Submonoid
./../../lib/monoid.gd:96 : MonoidByGenerators
./../../lib/monoid.gd:113 : AsMonoid
./../../lib/monoid.gd:133 : AsSubmonoid
./../../lib/monoid.gd:154 : GeneratorsOfMonoid
./../../lib/monoid.gd:173 : TrivialSubmonoid
./../../lib/monoid.gd:194 : FreeMonoid
./../../lib/semigrp.gd:507 : IsRegularSemigroup
./../../lib/semigrp.gd:487 : IsRegularSemigroupElement
./../../lib/semigrp.gd:371 : IsSimpleSemigroup
./../../lib/semigrp.gd:389 : IsZeroSimpleSemigroup
./../../lib/semigrp.gd:354 : IsZeroGroup
./../../lib/semigrp.gd:424 : IsReesCongruenceSemigroup
./../../lib/smgideal.gd:19 : SemigroupIdealByGenerators
./../../lib/smgideal.gd:60 : ReesCongruenceOfSemigroupIdeal
./../../lib/smgideal.gd:39 : IsLeftSemigroupIdeal
./../../lib/semicong.gd:109 : IsSemigroupCongruence
./../../lib/semicong.gd:127 : IsReesCongruence
./../../lib/semiquo.gd:38 : IsQuotientSemigroup
./../../lib/semiquo.gd:55 : HomomorphismQuotientSemigroup
./../../lib/semiquo.gd:75 : QuotientSemigroupPreimage
./../../lib/semirel.gd:88 : GreensRRelation
./../../lib/semirel.gd:56 : IsGreensRelation
./../../lib/semirel.gd:162 : IsGreensClass
./../../lib/semirel.gd:242 : IsGreensLessThanOrEqual
./../../lib/semirel.gd:263 : RClassOfHClass
./../../lib/semirel.gd:352 : EggBoxOfDClass
./../../lib/semirel.gd:371 : DisplayEggBoxOfDClass
./../../lib/semirel.gd:118 : GreensRClassOfElement
./../../lib/semirel.gd:210 : GreensRClasses
./../../lib/semirel.gd:288 : GroupHClassOfGreensDClass
./../../lib/semirel.gd:333 : IsGroupHClass
./../../lib/semirel.gd:307 : IsRegularDClass
./reesmat.xml:452 : AssociatedReesMatrixSemigroupOfDClass
./../../lib/fpsemi.gd:69 : IsSubsemigroupFpSemigroup
./../../lib/fpmon.gd:53 : IsSubmonoidFpMonoid
./../../lib/fpsemi.gd:156 : IsFpSemigroup
./../../lib/fpmon.gd:138 : IsFpMonoid
./../../lib/fpsemi.gd:20 : IsElementOfFpSemigroup
./../../lib/fpmon.gd:18 : IsElementOfFpMonoid
...
./../../lib/domain.gd:322 : InParentFOA
./../../lib/oprt.gd:449 : OrbitsishOperation
./../../lib/oprt.gd:704 : OrbitishFO
****************************************************************
*** Doc coverage report 
****************************************************************
2810 mansections 
1289 with examples 
1521 without examples 
****************************************************************