Fixed doxygen comments, focused on file headers and group definitions by haukepetersen · Pull Request #251 · RIOT-OS/RIOT

haukepetersen · 2013-10-21T16:38:56Z

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:

Copyright
Group assignment
File information
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 <xyz@awesome.com>
 */

// 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 <xyz@awesome.com>
 * @}
 */

// 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 · 2013-10-21T19:10:35Z

Welcome on board! ;)

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

OlegHahm · 2013-10-22T08:12:12Z

@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 · 2013-10-22T10:25:20Z

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 · 2013-10-22T11:04:43Z

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 · 2013-10-22T11:54:45Z

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 · 2013-10-22T11:55:40Z

Yes, sounds very reasonable, will do!

kaspar030 · 2013-10-22T12:13:36Z

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

OlegHahm · 2013-10-28T22:15:29Z

Needs rebasing.

miri64 · 2013-11-03T14:00:31Z

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

mehlis · 2013-11-14T09:30:02Z

@haukepetersen ping

LudwigKnuepfer · 2013-11-22T22:03:25Z

@haukepetersen ping

miri64 · 2013-11-25T12:37:16Z

@haukepetersen ping?

LudwigKnuepfer · 2013-11-25T15:00:41Z

git co comments
git rebase master
git push -f

miri64 · 2013-11-26T14:31:35Z

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

haukepetersen · 2013-11-27T17:09:14Z

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 · 2013-11-28T10:55:22Z

sys/net/sixlowpan/lowpan.h

RIOT should be always capitalized.

haukepetersen · 2013-11-28T12:33:26Z

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 · 2013-12-15T21:25:29Z

Needs rebase

- added boards to riot.doxyfile - fixed group definitions for all boards

haukepetersen · 2013-12-16T13:02:14Z

Rebased...

miri64 · 2013-12-16T14:05:56Z

ACK

mehlis · 2013-12-16T14:12:51Z

ACK

ready for merge?

Fixed doxygen comments, focused on file headers and group definitions

remove thread_measure_stack_usage from kernel_internal.h again

docs: solved some warnings in the RC-22.06

miri64 mentioned this pull request Nov 3, 2013

Add POSIX compatible case insensitive compare #290

Merged

OlegHahm reviewed Nov 28, 2013
View reviewed changes

sys/net/sixlowpan/lowpan.h Outdated

Copy link
Copy Markdown

Member

OlegHahm Nov 28, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RIOT should be always capitalized.

haukepetersen added 3 commits December 16, 2013 14:00

Fixed doxygen comments, focused on file headers and group definitions

3785fe9

Fixed a lot of comments by removing tabs and correcting format.

edcabf7

Added the boards folder to the doxygen tree

c629229

- added boards to riot.doxyfile - fixed group definitions for all boards

Fixed doxygen inconsistensies in sys

2df8201

OlegHahm added a commit that referenced this pull request Dec 16, 2013

Merge pull request #251 from haukepetersen/comments

7d9dc6b

Fixed doxygen comments, focused on file headers and group definitions

OlegHahm merged commit 7d9dc6b into RIOT-OS:master Dec 16, 2013

thomaseichinger mentioned this pull request Dec 16, 2013

Simplify msp430 headers #408

Merged

haukepetersen deleted the comments branch December 16, 2013 18:48

haukepetersen restored the comments branch December 16, 2013 18:48

haukepetersen deleted the comments branch December 16, 2013 18:48

LudwigKnuepfer pushed a commit to LudwigKnuepfer/RIOT that referenced this pull request Jan 20, 2014

fix regression from RIOT-OS#251

c42aa89

remove thread_measure_stack_usage from kernel_internal.h again

CW-75 added a commit to CW-75/RIOT that referenced this pull request Jul 1, 2022

Merge pull request RIOT-OS#251 from eduazocar/feature/doc

33a5296

docs: solved some warnings in the RC-22.06

Conversation

haukepetersen commented Oct 21, 2013

Uh oh!

kaspar030 commented Oct 21, 2013

Uh oh!

OlegHahm commented Oct 22, 2013

Uh oh!

kaspar030 commented Oct 22, 2013

Uh oh!

haukepetersen commented Oct 22, 2013

Uh oh!

OlegHahm commented Oct 22, 2013

Uh oh!

haukepetersen commented Oct 22, 2013

Uh oh!

kaspar030 commented Oct 22, 2013

Uh oh!

OlegHahm commented Oct 28, 2013

Uh oh!

miri64 commented Nov 3, 2013

Uh oh!

mehlis commented Nov 14, 2013

Uh oh!

LudwigKnuepfer commented Nov 22, 2013

Uh oh!

miri64 commented Nov 25, 2013

Uh oh!

LudwigKnuepfer commented Nov 25, 2013

Uh oh!

miri64 commented Nov 26, 2013

Uh oh!

haukepetersen commented Nov 27, 2013

Uh oh!

OlegHahm Nov 28, 2013

Choose a reason for hiding this comment

Uh oh!

haukepetersen commented Nov 28, 2013

Uh oh!

OlegHahm commented Dec 15, 2013

Uh oh!

haukepetersen commented Dec 16, 2013

Uh oh!

miri64 commented Dec 16, 2013

Uh oh!

mehlis commented Dec 16, 2013

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants