Fixed doxygen comments, focused on file headers and group definitions

[haukepetersen]

Hi @ALL,

as I am new to RIOT I will give my first shot at putting a pull request together: while looking through the code I tried to clean up some of the doxygen comments in RIOT, mainly focusing on bringing the doxygen module structure in order. I tried to unify the page header comments to the following style and order:

1. Copyright
2. Group assignment
3. File information
4. Authors

I tried to use the following blueprint for each (.h) file:

/*
 * Copyright (C) 2013 Freie Universität Berlin
 *
 * This file subject to the terms and conditions of the GNU Lesser General
 * Public License. See the file LICENSE in the top level directory for more
 * details.
 */

/**
 * @addtogroup  core_util
 * @{
 */

/**
 * @file         filename.h
 * @brief       Description whats in that file
 * @author    Institution...
 * @author    Author xyz <[email protected]>
 */

// beautiful code

/** @} */

and for .c files:

/*
 * Copyright (C) 2013 Freie Universität Berlin
 *
 * This file subject to the terms and conditions of the GNU Lesser General
 * Public License. See the file LICENSE in the top level directory for more
 * details.
 */

/**
 * @addtogroup  core_util
 * @{
 * @file         filename.c
 * @brief       Short description of whats in here
 * 
 * If needed: long description of the file
 *
 * @author    Institution...
 * @author     Author xyz <[email protected]>
 * @}
 */

// here comes the code

For group definitions that are not clearly traceable to a specific file I inserted doc.txt files into the module folders (e.g. RIOT/core/doc.txt, RIOT/sys/net/doc.txt, ...). The location and naming of these files is surely something we should talk about...

[kaspar030]

Welcome on board! ;)

A quick look shows there are some whitespace issues. AFAIR we've decided to use 4 spaces instead of tabs.

[OlegHahm]

@kaspar030, you're right: https://github.com/RIOT-OS/RIOT/wiki/Coding-conventions#indentation-and-braces but I don't see where this PR breaks this (though I might have overlooked it).

Thanks for the work, @haukepetersen.

[kaspar030]

At least in mutex.h and msg.h some doxygen comments use e.g., tabs for @author and spaces for the rest, or vice-versa, in the same file. Can see that in github only whith a sharp eye.

@haukepetersen: looks like your last commit is astyling a lot more than the changes you've made before. ;)

[haukepetersen]

Oh, now I see it too - damnit. How should we proceed, should I revert the last commit and try to fix the tab issue maually only to the parts I changed or should we keep the other astyle fixes in as well (since the style in that code lines was not up to the standard anyway...)?

[OlegHahm]

Auto-astyling the whole code is not a good idea. At some particular places it makes sense to interpret the coding conventions a bit more flexible (e.g. astyle would make the lcd_font array in https://github.com/RIOT-OS/boards/blob/master/chronos/drivers/display1.c mostly unreadable).

Hence, I suggest to remove the last commit, ran astyle again, but commit only the files you've touched and review carefully if the astyling "breaks" anything.

[haukepetersen]

Yes, sounds very reasonable, will do!

[kaspar030]

coloured git-diff and searching for tab helps in manually fixing these things

[OlegHahm]

Needs rebasing.

[miri64]

After rebasing and fixing of the tab problem I'd like to ack this. Even used this documentation scheme in #290

[mehlis]

@haukepetersen ping

[LudwigKnuepfer]

@haukepetersen ping

[miri64]

@haukepetersen ping?

[LudwigKnuepfer]

git co comments
git rebase master
git push -f

[miri64]

git co does not exist in mainline git. Use git checkout instead ;-)

[haukepetersen]

Ok, sorry guys, took a while. But with Olegs help I was able to finally rebase the old commit. I pushed a second commit on top, where I fixed the tabs and some other formating issues.

[OlegHahm]

RIOT should be always capitalized.

[haukepetersen]

And here are two more amendments, now the boards folder is fully integrated after is was moved. Let me know if I should group all the commits together.

[OlegHahm]

Needs rebase

[haukepetersen]

Rebased...

[miri64]

ACK

[mehlis]

ACK

ready for merge?