Project

General

Profile

Support #75

Documentation review by Caleo

Added by John Abbott over 12 years ago. Updated over 11 years ago.

Status:
Closed
Priority:
Normal
Assignee:
-
Category:
Documentation
Target version:
-
Start date:
23 Dec 2011
Due date:
% Done:

100%

Estimated time:
75.00 h
Spent time:
74.50 h

Description

Alessandra Caleo has volunteered(?!?) to review the CoCoALib documentation & examples.

This "issue" keeps track of what she has done, and what she is doing.

Related issues

Related to CoCoALib - Support #195: OrdvArith documentation needs rewritingClosed2012-06-22

Related to CoCoA-5 - Support #242: CoCoA-5 Projects for students (e.g. crediti F and tesi)In Progress2012-09-28

History

#1 Updated by John Abbott over 12 years ago

  • Category set to Documentation
  • % Done changed from 0 to 10
Alessandra has checked the following parts:
  • BigInt
  • BigRat
  • RingElem (& ring)
  • matrix & MatrixView
  • NumTheory & NumTheoryQQ

She identified some non-trivial problems with matrix/MatrixView which Anna and John are working on.

#2 Updated by John Abbott over 12 years ago

Alessandra asked what to look at next (possibly during the holidays):
  • RingZZ
  • RingQQ
  • RingFp (3 versions)
  • FractionField
  • QuotientRing
  • RingTwinFloat (possibly)

JAA does not much like the names of the pseudo-ctors for FractionField & QuotientRing; can we think of something better?

#3 Updated by John Abbott about 12 years ago

Alessandra is busy with exams until early March (2012)

#4 Updated by John Abbott about 12 years ago

Alessandra reports:
  1. documentation for ring & RingElem is mostly OK (but still not complete)
    ex-RingElem1 is OK too (needs a little cleaning)
  2. it is not clear how to create new rings, nor why one must use RingZZ() -- what are the empty brackets for?
  3. doc for FractionField is mostly OK; but it is not clear why there is AsFractionField. We suggest adding doc about IsFractionField and AsFractionField to doc for ring.

#5 Updated by John Abbott about 12 years ago

Alessandra reports:
  • doc for almost all rings (except ring, RingElem) needs to be better organized
  • references to args in fn descriptions should be red-on-yellow
  • numerous minor mistakes (manual and/or examples)
  • it was not clear when a machine int must be converted explicitly to a RingElem.

Anna thinks that the handwritten doc should not contain the full function signatures (because they are often lengthy, and possibly confusing to new users with little experience in C++). For the time being one must refer to the header files to find the full signature. In the few cases where the correct signature cannot easily be guessed the handwritten doc should explain clearly in words.

Over the coming week Alessandra will finish the basic rings, and then move on to polynomial rings.

#6 Updated by John Abbott about 12 years ago

  • % Done changed from 10 to 20
Alessandra reports:
  1. the examples are mostly OK; she reported some minor problems which J+A attended to immediately.
  2. unclear how to create non-sparse poly rings.
  3. ex-RingFp2 was quite unclear -- it is hard to find inputs which are not fine for all types of small prime finite field.

Anna explained to Alessandra the format of the txt source files for the CoCoALib documentation.

#7 Updated by John Abbott about 12 years ago

  • % Done changed from 20 to 30
Alessandra reports
  • finished BigInt, BigRat and MachineInt (doc and examples)
  • bool3 doc was poor; the C++ example in the txt file was unhelpful (resolved 20120530)
  • doc for convert did not explain how to call any of the fn-procs (see #140)
  • in ex-NumTheory1 the output is not easy to understand (resolved 20120530)

JAA has just added a first version of doc for factorization.

#8 Updated by John Abbott almost 12 years ago

  • % Done changed from 30 to 40
Alessandra reports:
  • the examples 2,3,4 of ex-RingWeyl are almost identical -- this cannot be what is intended!
  • doc for RingWeyl is totally absent
  • matrices finished
  • some changes needed in doc for MatrixArith (resolved 20120530) and in MatrixSpecial

For next time Alessandra will check the PPMonoid family.

#9 Updated by John Abbott almost 12 years ago

Alessandra reports that the doc for PPMonoid did not explain clearly what a PPMonoid is, nor why CoCoALib offers them -- J&A will rectify ASAP.

The doc for PPWithMask is far too short to be properly comprehensible. What purpose does PPWithMask serve? How is it different from a normal PPMonoidElem?

The doc for DivMask... the description is fair (but needs to be improved), but it is unclear why there are many different sorts, and how one might choose the most appropriate one.

The example in ex-bool3.C is not clear because it is based on a little known mathematical result -- find a better-known example.

We have updated the manual for CpuTime following Alessandra's comments.

We have added an example gathering together the various basic C++ features which we take for granted in the other CoCoALib examples.

Alessandra will continue with the PPMonoid family.

#10 Updated by John Abbott almost 12 years ago

  • % Done changed from 40 to 50
Alessandra has looked at the doc and examples for:
  • PPMonoid -- approved by Alessandra!
  • symbol -- approved by Alessandra!
  • PPOrdering -- approved by Alessandra!

For the next meeting she will look at power product related fns e.g. degree, DivMask, PPWithMask, PPVector

Next meeting: Monday 2012-06-11

#11 Updated by Anna Maria Bigatti almost 12 years ago

doc for degree and PPVector needs a bit of cleaning (but is comprehensible anyway)

PPWithMask has a (now useless) example.

DynamicBitset: cleanup and explain it's mainly technicalities.

DivMask and DivMaskRule need more explanations.
Rename "NewDivMask.." into "NewDivMaskRule..."?
Otherwise it looks like we are constructing a DivMask with no PP
Probably we should first explain about DivMask and later about the different DivMaskRules.

hilbert doc is embarrassingly empty.

There is a "http://cocoa.dima.unige.it/cocoalib/doc/html/GMPAllocator.html" to be removed (now called differently)

#12 Updated by John Abbott almost 12 years ago

Alessandra reports:
  • doc for PPWithMask needs major improvement (and also the impl)
  • ex-PPWithMask2.C needs clearer comments explaining what the prog does
  • maintainer doc for QBGenerator is missing (current just a "sarky" comment)
  • doc for DynamicBitset needs more explanation
  • doc for OrdvArith contains an unrelated section about PPOrdering?!?

Next meeting 2012-07-13 at 11:00 (Friday the 13th!)

#13 Updated by John Abbott over 11 years ago

  • Estimated time changed from 100.00 h to 75.00 h

Alessandra has decided to do 3 rather than 4 credits.

#14 Updated by John Abbott over 11 years ago

Alessandra helped us
  • sort out doc for ideal, ApproxPts, BuildInfo, error
  • improve examples for AlexanderDual, ApproxPts1, BuildInfo, error1

For next time (2012-09-28) she will look at the remaining examples.

#15 Updated by John Abbott over 11 years ago

Alessandra:
  • several guidelines for improving DynamicBitset (doc and example)
  • approved symbol, ideal, factorization
  • approved changes to ApproxPoints, QBGenerator (doc and examples)

#16 Updated by John Abbott over 11 years ago

Alessandra reports:
  • examples/CopyInfo.C is not an example -- Anna has added a comment to the file
  • incomplete descriptions in ex-frobby.C (Anna will fix)
  • man page for GlobalManager is poorly organized and hard to follow; details about GMPAllocator are very scarce
  • need better descriptions in ex-GMPAllocator
  • approved ex-io and ex-limits

#17 Updated by John Abbott over 11 years ago

  • Status changed from New to Closed
  • % Done changed from 50 to 100
Alessandra reports:
  • what does flush do in ex-GMPAllocator2.C? (ok, fixed now)
  • ex-NF.C not mentioned in doc (ok, fixed now)
  • doc for PPOrdering is old-fashioned.
  • explain the variable NoPrompt in file ex-PolyInput1.C (ok, fixed now)
  • OK for ex-PolyIterator1.C
  • Anna will fix ex-PolyIterator2.C (needs a lot of work)
  • wrong short/long descriptions in ex-PPMonoidHom1.C, also needs improving -- JAA will fix
  • the doc & examples for the random generators were not entirely clear (partly improved)

Also available in: Atom PDF