Support #252
Documentation for tmp.H (utils on vectors and other containers)
Description
tmp.H includes some useful functions, such as sum, product, ...
but documentation is missing (of course, as it is called "tmp" ;-)
Maybe we should move these functions in utils.H?
History
#1
Updated by John Abbott over 11 years ago
Updated by - Category set to Documentation
My "gut feeling" is that code in tmp.C should not have official documentation.
However, from a practical point of view it is probably a good idea to develop some documentation for candidate new functions. Perhaps the documentation should simply be marked clearly as EXPERIMENTAL (or likely to change or whatever)?
#2
Updated by Anna Maria Bigatti about 10 years ago
Updated by John Abbott wrote:
My "gut feeling" is that code in
tmp.Cshould not have official documentation.However, from a practical point of view it is probably a good idea to develop some documentation for candidate new functions. Perhaps the documentation should simply be marked clearly as EXPERIMENTAL (or likely to change or whatever)?
tmp has some useful functions which should be documented.
Maybe it should be renamed into template
#3
Updated by Anna Maria Bigatti about 10 years ago
- Target version set to CoCoALib-0.99533 Easter14
#4
Updated by John Abbott about 10 years ago
- Target version changed from CoCoALib-0.99533 Easter14 to CoCoALib-0.99534 Seoul14
#5
Updated by John Abbott almost 10 years ago
- Status changed from New to Feedback
- Assignee set to John Abbott
- % Done changed from 0 to 90
- Estimated time set to 2.30 h
Renamed file to UtilsTemplate.H.
Moved LexCmp3 into the file (from utils.H).
Added doc (& moved doc for LexCmp3).
Added new example ex-UtilsTemplate1.C
Still need to improve HasUniqueOwner so that it works with any container.
#6
Updated by Anna Maria Bigatti almost 10 years ago
Should also << for vector/list be here?
(now it is in io.H)
#7
Updated by John Abbott almost 10 years ago
I suppose it makes sense to move them... perhaps I'll think about it overnight before acting.
#8
Updated by John Abbott almost 10 years ago
HasUniqueOwner should now work with any container. Checked in.
[I haven't actually made any specific tests, but the standard CoCoALib tests compile and pass]
#9
Updated by John Abbott almost 10 years ago
Christof does not like the name UtilsTemplates.H; he suggested UtilsContainers.H or UtilsVector.H saying that it would be a more helpful name for users -- actually most users would presumably just include library.H. I think he does have a valid point.
He also said that it would make sense to move the printing functions only if the header file name indicated that that is where they would likely be; he was concerned that they may end up "hidden" inside a header whose name is too vague.
Opinions?
#10
Updated by Anna Maria Bigatti almost 10 years ago
John Abbott wrote:
Christof does not like the name
UtilsTemplates.H; he suggestedUtilsContainers.HorUtilsVector.Hsaying that it would be a more helpful name for users -- actually most users would presumably just includelibrary.H. I think he does have a valid point.
OK... it would be quite helpful for me, at least.
I find templates scary, whereas I often wonder "where is that funcion on vector defined?" ;-)
(I can think of some other functions I might like to add to it, if we call it UtilsVector..)
#11
Updated by Anna Maria Bigatti almost 10 years ago
- Subject changed from Documentation for tmp.H to Documentation for tmp.H (utils on vectors and other containers)
#12
Updated by John Abbott over 9 years ago
- Status changed from Feedback to Closed
- % Done changed from 90 to 100
- Estimated time changed from 2.30 h to 5.30 h
The final (hasty?) decision is the call the file VectorOperations.H (even though most functions in it apply to other C++ containers as well). The printing functions for vector and list have been merged into it too -- so the old header files io.H and UtilsTemaplte.H have been removed.
All tests pass. Documentation and examples have been updated.
Checked in. Closing.