Ok, this is a long and intresting post, so i am going to take my time to answer to it
There is a big code-documentation-lazyness within the complete API-Documentation:
Most methods are explained very poorely, I guess the author "hacks" some functions into CS and maybe he writes a demoprogram or assumes that all other programmers in the world know what he knows.
I agree in part on this, lots of APIs are very poorly documented (or documentation out of date) while in other areas it is better. Myself I try to document what I write, but sometimes the documentation is not as good as one would expect it to be.
virtual bool csEvent::Add ( const char * name,
iBase * v
Wow, that's really useless. I can add a name. What should it look like? Where do I need it? What is "v"? So I'm going to surf around within the API and search for more information and in the worst case I don't find any.
Ok, this is one of the bad ones, i know it
Although, there is one problem here. Due to CS having everything split in interfaces (iEvent in this case) and implementation classes (csEvent) there will always be two "definitons" of every public method. At least I think it is ok if the proper documentation is in the interface (iEvent) and the implementation class just reference it's interface. Duplication leads to errors.
OK, now I'll tell you how to greatly improve the API-Docs:
1) Some hyperlinks would be good:
virtual csFlags& iPortal::GetFlags ( ) [pure virtual]
Set portal flags (see CS_PORTAL_XXX values).
"CS_PORTAL_XXX"? Hmm, *seeearch*
At least earlier doxygen had problems with documentation for macros (and i think CS_PORTAL_.. are macros, something whihc probably should be changed but that is another matter)
2) The API-Docs are really lame with the current settings, I change the .dox-files and compile it by my own since two years.
The Java-API is a good example how a documentation could be, I don't know how to code efficiently with less than that.
You can get something like this with doxygen too. It's a mighty tool, but you don't use it.
That is a bit a matter of personal preference
- Treeview really helps with the navigation. Someone postet a wiki-comment to the online docs some time ago. He asked if there will come content. I bet, with treeview he had instantly seen everything.
Myself i don't like the treeview, but as said aobve that is a matter of personal preference.
- The Searchengine shortens the time I need to search and it searches every place in the API. More time and less stress for me.
Might be worth enabling, given it does not require any special on the client or server to ues it
- Sorting... many methods currently are not sorted, that costs time. Please... Sorting is the very most important feature at all! I can't believe it's disabled.
From checking the .dox file for pubapi sorting should be enabled.
- Dot... I can see which class inherits/implements what, I see UML-diagrams from that class, I can click on that diagram and browse to dependant classes and more. That's really useful.
There have been problems in the past when dot was enabled. One of them is that the host then used to generate the docs (the sourceforge servers) took so long to generate it. Another problem is the size of the documentation.
3) Please throw away that stylesheet, it's ok but far away from best-readable. The default-stylesheet from doxygen 1.4.x has a much better layout and better colors, it's really charming.
Matter of personal preference
4) Please change your documentation-style (when you have one
), it's lazy, it's short, there is no difference to "no documentation at all" (see examples above).
I write large documentations even for methods that every idiot might understand:
Atm there is no specified documentation style, it is up to each coder to document as he likes. I see a point in what you are saying, on the other had i think overdocumentation is no good either. A simple SetName call should not need more than 1-2 lines of documentation, if it does you have done something wrong
I know, you will say "that is too much work", CS has hundreds of methods.
Right, it's too much work now, but there are four steps to polish the complete reference without many stress:
Your estimation is a bit on the low side
I just checked, and low counted CS have ~800 classes and about 4500 class members (public class members that is). Now most of those are documented but at least there are a few thousand comments to check.
1) every new method will get it's documentation en passant: Write the method and instantly documentate it. You don't have to do it later. And you should not do it later, because you forgot something or even think about the next two functions -> the docs are bad-style again
This already is the case (if it is not then that person should be spanked
. However CS have been written by over hundred person over a period of more than six years...
2) Whenever someone opens an old file to read/debug some existing code: documentate it/extend the docs from that method or the whole class.
This is good in theory. In practice that would lead to nobody fixing bugs
Another problem you are no thtinking about is that most people accualy don't know how quite a few things works and thus cannot document it...
3) Use grep to find all those "Document me!@@" and fix them first. Doxygen will think that this is a documentation and so it will not print warnings!
4) let doxygen write warnings into a file, read the warnings from that file and eliminate them. Step by step.
1)+2) may cost 1 - 10 minutes per method, but that doesn't hurt. In this time you can relax from coding and even think about what you've coded and if the code really does what the docs say.
3)+4) is more work, but with a good style this will be reduced to zero
5 minutes per method is no problem, that just makes ~8 days around the clock work
(at an estimation that half the methods in CS needs some kind of checking)
I think you have many good points above, but it is not just something you fix over a coffee-break
I think (and hope) that the quality will improve over time and a good way to accualy speed that up is to provide patches for documentation. CS have a limited number of developers and most of us do our best to make CS better but there is alwahys a need for more people doing things, and one of those things are writing better documentation.