Jon Keating wrote:
On Monday 25 June 2007 05:25, Erik Johansson wrote:
But I have yet to see such code and gcc will print a warning when you
compile it, so I don't think it's a strong argument. On the other
hand, the documentation and readability gains you get by using NULL is
well worth it, even if it's a "hack".
Well, we can use NULL then. I'd prefer to use nullptr though, but I'm pretty
sure most compilers don't support it. Unless it is in boost...
Anyway, I've updated the wiki with both your comments. If it looks ok
to you all, we can move on and start doing some coding :)
Looks fine to me. So, where should we start coding? I have played around a bit
with the erijo-dev branch and it seems to be a decent start. If we start to
use that as a base, then I guess it would make sense to assign certain
portions to people. I will see about finally finishing the document about
owners, using the comments that I received awhile ago.
After looking at the wiki I can't find anything to add at the moment,
however I have some comments on the comments =)
Apparently there were more than just /** or /// to choose between for
the documentation.
I'd prefer to use the javadoc style as I'm used to that and already
started using it in the qt4-gui. Example:
/**
* An example function.
* A longer description about the function...
* ........
* .....
* @param first Description of the first parameter
* @param second Description of the second parameter
* @return True if you're lucky
* @throws Rocks
*/
public bool exampleFunction(int first, string second) throws (Rocks);
To highlight the differences:
* Having asterisks on all the lines marks the comment and makes it stand
out more from the rest of the code.
* The @brief isn't necessary from what I've read. By default the first
sentence or line will be used and there is no need for an empty line
between the brief and the longer description.
* Starting on the second line seems to be standard for javadoc and that
also controls which indentation to use for the rest of the comment.
* Adding [in] and [out] on the parameters however looks like a good idea
as it adds important information. (Although I would prefer to have
multiple return values instead of having to put return variables as
input parameters. Yes I like perl ;-) )
Also after reading "Before committing, generate the doxygen
documentation and check it to make sure it's sane." I think it should
say how to generate it. Or if there is something that could be added to
the makefiles to make it easy to generate, do that.
/Anders
