Doxygen support

[devnoname120]

Add Doxygen support.

WIP:

• Add Doxygen configuration
• Group related modules in supergroups (e.g. audio-related libraries should be in the supergroup Audio)
  - [ ] Merge multi-line comments
• Add aliases for include/library hints
  - [ ] Move license to the top without using doxygen-type comments
• Simplify the header doxygen as much as possible

---

HTML documentation can be generated using:

cd docs
doxygen Doxyfile

Preview: http://devnoname120.legtux.org/vitaheadershtml/index.html

[devnoname120]

Groups are now in categories, this should make the documentation more readable.

Note: In order for the groups to be collapsed by default, we need to modify modules.html, and replace

  $(document).ready(function() { init_search(); });

with

  $(document).ready(function() { init_search(); toggleLevel(1); });

---

I think that this pull request is ready for merging, here is the final result: http://devnoname120.legtux.org/vitaheadershtml/index.html

[d3m3vilurr]

well.. can you check result after swap new header part(define group) and license part(file brief).
if doxygen make same result, please swap these.
IMO, changing position of license part to top of file looks more good then this. :)

[devnoname120]

I tried to swap them, but then the section file doesn't appear in the documentation. Among other things, this allows the reader to see the source code of the header file.

[d3m3vilurr]

well, many code licenses suggest their information attach to top of file.

problem might be \defgroup but also i don't know how fix this :/ (i not build docs, yet.)

IMO, generated doc can allow missing license info.
so just extract copyright parts then move to top, it's probably ok.
or we can consider to add newer tags in files like \author, \copyright...

[d3m3vilurr]

few minute ago, i checked this pr in my local. my doxygen version is 1.8.11, and both case(swap and non-swap) out same result.

so please swap these. ;-)

[devnoname120]

[noname120PC@noname120 docs]$ doxygen -v
1.8.12

---

Without changing anything:

/**
 * \addtogroup Kernel Kernel
 * Modules, Processes, Threads, Memory blocks
 * \{
 */

/**
 * \addtogroup SceThreadMgr Thread Manager Library
 * List the running threads, start, stop and send a message.
 */
/** \} */

/**
 * \defgroup SceThreadMgrUser User
 *  \ingroup SceThreadMgr
 * Exports for User
 *
 * ------------------------
 * ### Using this library in your project ###
 * Include the header file in your project:
 * \code
 * #include <psp2/kernel/threadmgr.h>
 * \endcode
 *
 * Link the library in your makefile:
 * \code
 * -lSceKernel_stub
 * \endcode
 * ------------------------
 * \{
 */

/**
 * \file
 * \brief Header file related to thread management
 *
 * Copyright (C) 2015 PSP2SDK Project
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 */

---

Adding the file at the top:

/**
 * \file
 * \brief Header file related to thread management
 *
 * Copyright (C) 2015 PSP2SDK Project
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 */

/**
 * \addtogroup Kernel Kernel
 * Modules, Processes, Threads, Memory blocks
 * \{
 */

/**
 * \addtogroup SceThreadMgr Thread Manager Library
 * List the running threads, start, stop and send a message.
 */
/** \} */

/**
 * \defgroup SceThreadMgrUser User
 *  \ingroup SceThreadMgr
 * Exports for User
 *
 * ------------------------
 * ### Using this library in your project ###
 * Include the header file in your project:
 * \code
 * #include <psp2/kernel/threadmgr.h>
 * \endcode
 *
 * Link the library in your makefile:
 * \code
 * -lSceKernel_stub
 * \endcode
 * ------------------------
 * \{
 */

[devnoname120]

In the second case, the section file is missing. It's better to keep it so that the user can take a quick peak at the header file if needed.

I think that licenses should be at the top of the files, without using Doxygen-style comments. But this is outside the scope of this pull request, I can open another one if you wish in order to fix this.

[d3m3vilurr]

if not allocate that position, it occur broke link in that file. yeah i got it, \defgroup problem. :)

anyway, i'm not use doxygen in my personal projects for the documentation, so i don't know right or common format.
also i want to reduce mean less commit after this pr. so i added review comments for the deciding document format

and remain review thing;
in my test, multiple comments block is useless.

/**
 * \addtogroup SystemStatus System Status
 * Time, battery...
 * \{
 *  \addtogroup SceAppMgr Application Manager Library
 *  Launch Apps and get their params
 * \}
 * \defgroup SceAppMgrUser User
 *  \ingroup SceAppMgr
 * Exports for User
 *
 * ------------------------
 * ### Using this library in your project ###
 * Include the header file in your project:
 * \code
 * #include <psp2/appmgr.h>
 * \endcode
 *
 * Link the library in your Makefile:
 * \code
 * -lSceAppMgr_stub
 * \endcode
 * ------------------------
 * \{
 *
 * \file
 * \brief Header file which defines control related variables and functions
 *
 * Copyright (C) 2015 PSP2SDK Project
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 */

it's still long but IDK fix method :/

anyway your work is great, doxygen result look awesome ;)

[devnoname120]

Hm, I can't seem to see your review comments.
Multi-block comments are indeed useless, I'll merge them.

Also, I will define some special aliases so as to make the include/library hint less verbose.

Thanks!

[devnoname120]

I have simplified the way grouping works by defining the group hierarchy in docs/definitions.h and adding a few custom commands, most notably \usergroup{groupname}, \kernelgroup{groupname}, and \usage{include_header.h,-lMyLibrary}.

Here is what a header now looks like:

/**
 * \usergroup{SceAppUtil}
 * \usage{psp2/apputil.h,-lSceAppUtil_stub}
 */

I have not merged the doxygen comments since we now only have one for the whole grouping, and it makes easier to visually distinguish it with the license part.

Is there anything else to change?

[d3m3vilurr]

look nice, but that patch was added docs/definitions.h to file list.
how about change filename to docs/definitions.dox?

[devnoname120]

Done.