The very best and most important feature...

[mark]

...would be a verbose and better API-Documentation.

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.
Every time I read the API, I think that the author thought "My style is clearly enough, it doesn't need some time-wasting, lame documentation.
Writing some doxygen lines is really too exhausting."

Writing what a method does, what it's parameters are and what the method returns is very important to know - in complete sentences and no reduced short form.

Some bad examples:

Code:

virtual bool csEvent::Add   (   const char *   name,
  iBase *   v
  )    [virtual]
     
  Implements iEvent.

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.

There are more examples that are even worse, because there is no documentation (or just something like "Document me!@@.") the identifiers' names are unusable for guessing what their use could be ("o", "v", ...), ....

Another example:

Code:

virtual void iJob::Run   (    )    [pure virtual]
     
  Do stuff.

"Do stuff". Yeah. Dance the monkey shuffle? Delete my files? Or just "for(;;);"?


OK, now I'll tell you how to greatly improve the API-Docs:

1) Some hyperlinks would be good:

Code:

virtual csFlags& iPortal::GetFlags   (    )    [pure virtual]
     
  Set portal flags (see CS_PORTAL_XXX values).

"CS_PORTAL_XXX"? Hmm, *seeearch*

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.
(http://java.sun.com/j2se/1.5.0/docs/api/index.html)
You can get something like this with doxygen too. It's a mighty tool, but you don't use it.

Use Treeview, Searchengine, Dot, let doxygen sort the methods, ... and the API-Website becomes usable.
Check it out: http://www.stack.nl/~dimitri/doxygen/config.html
- 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.
- The Searchengine shortens the time I need to search and it searches every place in the API. More time and less stress for me.
- 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.
- 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.

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.

4) Please change your documentation-style (when you have one :-P), 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:

Code:

/**
 * This method sets/changes the name of the player.
 * \param name This is the name, the player should get. It may have any length and unicode-chars too.
 * \return true when setting/changing the name was successfull
 * \return false when setting/changing the name was not successfull
 */
bool Player::setName(csString name);

I guess the CS-version would be:

Code:

/**
 * Sets the players name
 */
bool Player::setName(csString name);

or

Code:

/**
 * Sets the players name
 * \param name The name.
 */
bool Player::setName(csString name);

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:
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
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.
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

Please, please, please, please do it and all programmers out there will worship you; yet they just curse you ;-)

Please, please, please, please, please. *conjure* *beg on my knees* *bow*

[deckerego]

I never really found a problem with the documentation - but more explicit descriptions never hurt anyone. I'd say go ahead and start documenting away - then submit it to the crew for inclusion. I'm sure if you got the ball rolling with documentation processes then future code could follow suit.

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.

Code:

virtual bool csEvent::Add   (   const char *   name,
  iBase *   v
  )    [virtual]
     
  Implements iEvent.

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:

Code:

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.
(http://java.sun.com/j2se/1.5.0/docs/api/index.html)
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.

Se above..

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.

-Mårten

[mark]

http://crystalspace3d.org/docs/online/api/structiVFS.php is not sorted.

For example, SetFileTime is listed before GetFileSize.
-> "SORT_BRIEF_DOCS
 If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief descriptions of file, namespace and class members alphabetically by member name. If set to NO (the default) the members will appear in declaration order."

CELs API is unsorted too.

The searchengine needs php4. No problem with tikiwiki I guess =)

[pilu30000]

I have recently started using Crystal Space, mainly because I believe it's one of the best free engine out there. Unfortunately though, it's almost impossible to get started as once you've completed all tutorials, there is nothing left to learn.
I mean, people shouldn't be expected to interpret complex applications to learn a particular function of the engine.
Even though it's quite complex to create, a documentation like the win32api one would surely make it easier to get started with crystal space.
The win32api structure is quite simple. A brief description of the function is given (listing of params etc) and a "remark" section is present when needed. At the bottom of the page there are links referring to similar topics, and some VERY SIMPLE examples are present. These examples are simple enough to be clear, but at the same time they use enough functions to be a good explaination of several functions. This means you could expect an example to be a valid explaination of 15-20 functions.
Assuming you need to write examples for , let's say, 3000 class members, it would actually take you 200 examples... being those quite easy to write.. it could take you.. hum... 45 minutes each? this means 150h... 2h/day , this means "loosing" less than three months (or 1 month if you r helped by two other ppl). This would make this great engine available to everybody's comprehension. I think the effort is worth it.