Merge lp:~thomas-voss/platform-api/add-documentation-part-1 into lp:platform-api

[Thomas Voß]

Add first wave of doxygen documentation and make the documentation known to the packaging setup.

Add first wave of doxygen documentation and make the documentation known to the packaging setup.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:82
http://jenkins.qa.ubuntu.com/job/platform-api-ci/66/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-amd64-ci/36
    SUCCESS: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-armhf-ci/36
        deb: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-armhf-ci/36/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-i386-ci/36

Click here to trigger a rebuild:
http://s-jenkins:8080/job/platform-api-ci/66/rebuild

review: Approve (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:82
No commit message was specified in the merge proposal. Click on the following link and set the commit message (if you want a jenkins rebuild you need to trigger it yourself):
https://code.launchpad.net/~thomas-voss/platform-api/add-documentation-part-1/+merge/173174/+edit-commit-message

http://jenkins.qa.ubuntu.com/job/platform-api-ci/67/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-amd64-ci/37
    SUCCESS: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-armhf-ci/37
        deb: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-armhf-ci/37/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-i386-ci/37

Click here to trigger a rebuild:
http://s-jenkins:8080/job/platform-api-ci/67/rebuild

review: Needs Fixing (continuous-integration)

[lp:~thomas-voss/platform-api/add-documentation-part-1]

83. By Thomas Voß on 2013-07-05

[ Thomas Voß ]
* * Adjust the cmake setup and get rid of -DUSE_GLES, instead rely on
  automatic detection if the header is available. * Adjust the cmake
  setup to bail out if EGL is not available. * Adjust the cmake setup
  to autogenerate doxygen API documentation.
* * Add a pkgconfig file for the platform API * Adjust installation of
  header files to account for version.
[ Ubuntu daily release ]
* Automatic snapshot from revision 84

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:83
No commit message was specified in the merge proposal. Click on the following link and set the commit message (if you want a jenkins rebuild you need to trigger it yourself):
https://code.launchpad.net/~thomas-voss/platform-api/add-documentation-part-1/+merge/173174/+edit-commit-message

http://jenkins.qa.ubuntu.com/job/platform-api-ci/73/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-amd64-ci/43
    SUCCESS: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-armhf-ci/43
        deb: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-armhf-ci/43/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-i386-ci/43

Click here to trigger a rebuild:
http://s-jenkins:8080/job/platform-api-ci/73/rebuild

review: Needs Fixing (continuous-integration)

[Didier Roche-Tolomelli (didrocks)]

+Depends: libplatform-api1-dev
-> you are missing a comma here

debian/libplatform-api1-dev.doc-base
-> I think that should be in the -doc package, right?

Otherwise looking good, you can merge once you fixed that :)

[lp:~thomas-voss/platform-api/add-documentation-part-1]

84. By Thomas Voß on 2013-07-05

Addressing review comments.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:84
http://jenkins.qa.ubuntu.com/job/platform-api-ci/75/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-amd64-ci/45
    SUCCESS: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-armhf-ci/45
        deb: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-armhf-ci/45/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/platform-api-saucy-i386-ci/45

Click here to trigger a rebuild:
http://s-jenkins:8080/job/platform-api-ci/75/rebuild

review: Approve (continuous-integration)

[lp:~thomas-voss/platform-api/add-documentation-part-1]

85. By Thomas Voß on 2013-07-05

 Adjust Document:-line.

[Ricardo Salveti (rsalveti)]

Good.

review: Approve

[PS Jenkins bot (ps-jenkins)]

review: Approve (continuous-integration)

=== modified file 'debian/control'
--- debian/control	2013-07-05 16:37:30 +0000
+++ debian/control	2013-07-05 16:37:30 +0000
@@ -39,10 +39,19 @@
          libplatform-api-headers (= ${binary:Version}),
          libplatform-api1-hybris | libplatform-api1,
          ${misc:Depends},
+Suggests: libplatform-api1-doc,
 Description: Platform API for system level capabilities (development)
  This package provides the development library and headers (via
  dependency) for the Platform API.
 
+Package: libplatform-api1-doc
+Section: doc
+Architecture: any
+Depends: libplatform-api1-dev,
+         ${misc:Depends},
+Description: Platform API for system level capabilities (development)
+ This package provides the developer documentation for the Platform API.
+
 Package: libplatform-api1-hybris
 Section: libs
 Architecture: any

=== added file 'debian/libplatform-api1-doc.doc-base'
--- debian/libplatform-api1-doc.doc-base	1970-01-01 00:00:00 +0000
+++ debian/libplatform-api1-doc.doc-base	2013-07-05 16:37:30 +0000
@@ -0,0 +1,8 @@
+Document: ubuntu-platform-api 
+Title: Ubuntu Platform API Reference Documentation
+Author: Thomas Voß
+Abstract: This is the reference documentation for the Ubuntu Platform API
+Section: Debian
+Format: HTML
+Index: /usr/share/doc/ubuntu-platform-api/html/index.html
+Files: /usr/share/doc/ubuntu-platform-api/html/*.html

=== added file 'debian/libplatform-api1-doc.install'
--- debian/libplatform-api1-doc.install	1970-01-01 00:00:00 +0000
+++ debian/libplatform-api1-doc.install	2013-07-05 16:37:30 +0000
@@ -0,0 +1,1 @@
+usr/share/doc/ubuntu-platform-api
\ No newline at end of file

=== modified file 'doc/CMakeLists.txt'
--- doc/CMakeLists.txt	2013-06-11 09:40:30 +0000
+++ doc/CMakeLists.txt	2013-07-05 16:37:30 +0000
@@ -26,5 +26,5 @@
     COMMENT "Generating API documentation with Doxygen" VERBATIM)
   install(
     DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
-    DESTINATION share/ubuntu-platform-api/doc)
+    DESTINATION share/doc/ubuntu-platform-api)
 endif(DOXYGEN_FOUND)
\ No newline at end of file

=== modified file 'doc/Doxyfile.in'
--- doc/Doxyfile.in	2013-07-05 16:37:30 +0000
+++ doc/Doxyfile.in	2013-07-05 16:37:30 +0000
@@ -26,7 +26,7 @@
 # identify the project. Note that if you do not use Doxywizard you need
 # to put quotes around the project name if it contains spaces.
 
-PROJECT_NAME           = @CMAKE_PROJECT_NAME@
+PROJECT_NAME           = "Ubuntu Platform API"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number.
 # This could be handy for archiving the generated documentation or
@@ -38,7 +38,7 @@
 # for a project that appears at the top of each page and should give viewer
 # a quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          =
+PROJECT_BRIEF          = "A library helping with tight integration into the Ubuntu platform"
 
 # With the PROJECT_LOGO tag one can specify an logo or icon that is
 # included in the documentation. The maximum height of the logo should not
@@ -668,7 +668,7 @@
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/../include
+INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@ @CMAKE_CURRENT_SOURCE_DIR@/../include
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -728,7 +728,7 @@
 # directories that contain example code fragments that are included (see
 # the \include command).
 
-EXAMPLE_PATH           = @CMAKE_CURRENT_SOURCE_DIR@/../examples
+EXAMPLE_PATH           = @CMAKE_CURRENT_SOURCE_DIR@/../src
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
@@ -791,7 +791,7 @@
 # This can be useful if you have a project on for instance GitHub and want reuse
 # the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = @CMAKE_CURRENT_SOURCE_DIR@/mainpage.md
 
 #---------------------------------------------------------------------------
 # configuration options related to source browsing
@@ -807,7 +807,7 @@
 # Setting the INLINE_SOURCES tag to YES will include the body
 # of functions and classes directly in the documentation.
 
-INLINE_SOURCES         = YES
+INLINE_SOURCES         = NO
 
 # Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
 # doxygen to hide any special comment blocks from generated source code
@@ -975,7 +975,7 @@
 # documentation will contain sections that can be hidden and shown after the
 # page has loaded.
 
-HTML_DYNAMIC_SECTIONS  = NO
+HTML_DYNAMIC_SECTIONS  = YES
 
 # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of
 # entries shown in the various tree structured indices initially; the user
@@ -1145,7 +1145,7 @@
 # navigation tree you can set this option to NO if you already set
 # GENERATE_TREEVIEW to YES.
 
-DISABLE_INDEX          = NO
+DISABLE_INDEX          = YES
 
 # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
 # structure should be generated to display hierarchical information.
@@ -1157,7 +1157,7 @@
 # Since the tree basically has the same information as the tab index you
 # could consider to set DISABLE_INDEX to NO when enabling this option.
 
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 
 # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values
 # (range [0,1..20]) that doxygen will group on one line in the generated HTML
@@ -1434,7 +1434,7 @@
 # If the GENERATE_MAN tag is set to YES (the default) Doxygen will
 # generate man pages
 
-GENERATE_MAN           = NO
+GENERATE_MAN           = YES
 
 # The MAN_OUTPUT tag is used to specify where the man pages will be put.
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be

=== modified file 'doc/mainpage.md'
--- doc/mainpage.md	2013-02-14 16:25:13 +0000
+++ doc/mainpage.md	2013-07-05 16:37:30 +0000
@@ -1,4 +1,4 @@
-Ubuntu Platform API	{#mainpage}
+Ubuntu Platform API {#mainpage}
 ===================
 
 The Ubuntu platform API Implements access to the Ubuntu platform and

=== modified file 'include/ubuntu/application/archive.h'
--- include/ubuntu/application/archive.h	2013-06-03 20:54:26 +0000
+++ include/ubuntu/application/archive.h	2013-07-05 16:37:30 +0000
@@ -14,7 +14,7 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
  * Authored by: Ricardo Mendoza <[e-mail]>
- *              Thomas Voß <[e-mail]>           
+ *              Thomas Voß <[e-mail]>
  */
 
 #ifndef UBUNTU_APPLICATION_ARCHIVE_H_
@@ -26,139 +26,311 @@
 
 struct UApplicationArchive;
 
+/**
+ * \brief Creates a new archive, ownership is transferred to caller.
+ * \ingroup application_support
+ * \sa u_application_archive_destroy
+ * \returns A new archive instance or NULL if not enough memory is available.
+ */
 UApplicationArchive*
 u_application_archive_new();
 
+/**
+ * \brief Destroys the given archive instance and releases all resources held by the instance.
+ * \ingroup application_support
+ * \param[in] archive The instance to be destroyed.
+ * \post All resources held by the instance are released. The result of any operation invoked on the destroyed instance are undefined.
+ */
 void
 u_application_archive_destroy(
-	UApplicationArchive *archive);
-
-UStatus
-u_application_archive_write(
-	UApplicationArchive *archive,
-	int8_t c);
-
-UStatus
-u_application_archive_write(
-	UApplicationArchive *archive,
-	uint8_t c);
-
-UStatus
-u_application_archive_write(
-	UApplicationArchive *archive,
-	int16_t s);
-
-UStatus
-u_application_archive_write(
-	UApplicationArchive *archive,
-	uint16_t s);
-
-UStatus
-u_application_archive_write(
-	UApplicationArchive *archive,
-	int32_t s);
-
-UStatus
-u_application_archive_write(
-	UApplicationArchive *archive,
-	uint32_t s);
-
-UStatus
-u_application_archive_write(
-	UApplicationArchive *archive,
-	int64_t s);
-
-UStatus
-u_application_archive_write(
-	UApplicationArchive *archive,
-	uint64_t s);
-
+    UApplicationArchive *archive);
+
+/**
+ * \brief Writes a signed 8-bit integer to the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to write to.
+ * \param[in] c The signed 8-bit integer to write to the archive.
+ */
+UStatus
+u_application_archive_write(
+    UApplicationArchive *archive,
+    int8_t c);
+
+/**
+ * \brief Writes an unsigned 8-bit integer to the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to write to.
+ * \param[in] c The unsigned 8-bit integer to write to the archive.
+ */
+UStatus
+u_application_archive_write(
+    UApplicationArchive *archive,
+    uint8_t c);
+
+/**
+ * \brief Writes a signed 16-bit integer to the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to write to.
+ * \param[in] s The signed 16-bit integer to write to the archive.
+ */
+UStatus
+u_application_archive_write(
+    UApplicationArchive *archive,
+    int16_t s);
+
+/**
+ * \brief Writes an unsigned 16-bit integer to the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to write to.
+ * \param[in] s The unsigned 16-bit integer to write to the archive.
+ */
+UStatus
+u_application_archive_write(
+    UApplicationArchive *archive,
+    uint16_t s);
+
+/**
+ * \brief Writes a signed 32-bit integer to the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to write to.
+ * \param[in] s The signed 32-bit integer to write to the archive.
+ */
+UStatus
+u_application_archive_write(
+    UApplicationArchive *archive,
+    int32_t s);
+
+/**
+ * \brief Writes an unsigned 32-bit integer to the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to write to.
+ * \param[in] s The unsigned 32-bit integer to write to the archive.
+ */
+UStatus
+u_application_archive_write(
+    UApplicationArchive *archive,
+    uint32_t s);
+
+/**
+ * \brief Writes a signed 64-bit integer to the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to write to.
+ * \param[in] s The signed 64-bit integer to write to the archive.
+ */
+UStatus
+u_application_archive_write(
+    UApplicationArchive *archive,
+    int64_t s);
+
+/**
+ * \brief Writes an unsigned 64-bit integer to the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to write to.
+ * \param[in] s The unsigned 64-bit integer to write to the archive.
+ */
+UStatus
+u_application_archive_write(
+    UApplicationArchive *archive,
+    uint64_t s);
+
+/**
+ * \brief Writes a string of characters to the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to write to.
+ * \param[in] s The string to write.
+ * \param[in] size The number of characters to write to the archive.
+ */
 UStatus
 u_application_archive_write_stringn(
-	UApplicationArchive *archive,
-	const char *s,
-	size_t size);
+    UApplicationArchive *archive,
+    const char *s,
+    size_t size);
 
+/**
+ * \brief Writes a string of wide characters to the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to write to.
+ * \param[in] s The string to write.
+ * \param[in] size The number of characters to write to the archive.
+ */
 UStatus
 u_application_archive_write_wstringn(
-	UApplicationArchive *archive,
-	const wchar_t *s,
-	size_t size);
+    UApplicationArchive *archive,
+    const wchar_t *s,
+    size_t size);
 
+/**
+ * \brief Writes a blob of binary data to the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to write to.
+ * \param[in] data The binary blob to write.
+ * \param[in] size The size of the blob.
+ */
 UStatus
 u_application_archive_write_bytes(
-	UApplicationArchive *archive,
-	const intptr_t *data,
-	size_t size);
+    UApplicationArchive *archive,
+    const intptr_t *data,
+    size_t size);
 
 UStatus
 u_application_archive_write_begin_blockn(
-	UApplicationArchive* archive,
-	const char *name,
-	size_t size);
+    UApplicationArchive* archive,
+    const char *name,
+    size_t size);
 
 UStatus
 u_application_archive_write_end_blockn(
-	UApplicationArchive* archive,
-	const char *name,
-	size_t size);
-
-UStatus
-u_application_archive_read(
-	const UApplicationArchive *archive,
-	int8_t *c);
-
-UStatus
-u_application_archive_read(
-	const UApplicationArchive *archive,
-	uint8_t *c);
-
-UStatus
-u_application_archive_read(
-	const UApplicationArchive *archive,
-	int16_t *s);
-
-UStatus
-u_application_archive_read(
-	const UApplicationArchive *archive,
-	uint16_t *s);
-
-UStatus
-u_application_archive_read(
-	const UApplicationArchive *archive,
-	int32_t *s);
-
-UStatus
-u_application_archive_read(
-	const UApplicationArchive *archive,
-	uint32_t *s);
-
-UStatus
-u_application_archive_read(
-	const UApplicationArchive *archive,
-	int64_t *s);
-
-UStatus
-u_application_archive_read(
-	const UApplicationArchive *archive,
-	uint64_t *s);
-
+    UApplicationArchive* archive,
+    const char *name,
+    size_t size);
+
+/**
+ * \brief Reads a signed 8-bit integer from the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to read from.
+ * \param[out] c Pointer to memory that receives the signed 8-bit integer.
+ */
+UStatus
+u_application_archive_read(
+    const UApplicationArchive *archive,
+    int8_t *c);
+
+/**
+ * \brief Reads an unsigned 8-bit integer from the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to read from.
+ * \param[out] c Pointer to memory that receives the unsigned 8-bit integer.
+ */
+UStatus
+u_application_archive_read(
+    const UApplicationArchive *archive,
+    uint8_t *c);
+
+/**
+ * \brief Reads a signed 16-bit integer from the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to read from.
+ * \param[out] s Pointer to memory that receives the signed 16-bit integer.
+ */
+UStatus
+u_application_archive_read(
+    const UApplicationArchive *archive,
+    int16_t *s);
+
+/**
+ * \brief Reads an unsigned 16-bit integer from the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to read from.
+ * \param[out] s Pointer to memory that receives the unsigned 16-bit integer.
+ */
+UStatus
+u_application_archive_read(
+    const UApplicationArchive *archive,
+    uint16_t *s);
+
+/**
+ * \brief Reads a signed 32-bit integer from the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to read from.
+ * \param[out] s Pointer to memory that receives the signed 32-bit integer.
+ */
+UStatus
+u_application_archive_read(
+    const UApplicationArchive *archive,
+    int32_t *s);
+
+/**
+ * \brief Reads an unsigned 32-bit integer from the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to read from.
+ * \param[out] s Pointer to memory that receives the unsigned 32-bit integer.
+ */
+UStatus
+u_application_archive_read(
+    const UApplicationArchive *archive,
+    uint32_t *s);
+
+/**
+ * \brief Reads a signed 64-bit integer from the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to read from.
+ * \param[out] s Pointer to memory that receives the signed 64-bit integer.
+ */
+UStatus
+u_application_archive_read(
+    const UApplicationArchive *archive,
+    int64_t *s);
+
+/**
+ * \brief Reads an unsigned 64-bit integer from the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to read from.
+ * \param[out] s Pointer to memory that receives the unsigned 64-bit integer.
+ */
+UStatus
+u_application_archive_read(
+    const UApplicationArchive *archive,
+    uint64_t *s);
+
+/**
+ * \brief Reads a string of characters from the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to read from.
+ * \param[out] s Pointer to memory that receives the string.
+ * \param[out] size Pointer to memory that receives the size of the string.
+ */
 UStatus
 u_application_archive_read_stringn(
-	const UApplicationArchive *archive,
-	const char **s,
-	size_t *size);
+    const UApplicationArchive *archive,
+    const char **s,
+    size_t *size);
 
+/**
+ * \brief Reads a string of wide characters from the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to read from.
+ * \param[out] s Pointer to memory that receives the wide string.
+ * \param[out] size Pointer to memory that receives the size of the string.
+ */
 UStatus
 u_application_archive_read_wstringn(
-	UApplicationArchive *archive,
-	const wchar_t *s,
-	size_t size);
+    UApplicationArchive *archive,
+    const wchar_t *s,
+    size_t size);
 
+/**
+ * \brief Reads a blob of binary data from the supplied archive
+ * \ingroup application_support
+ * \returns U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
+ * \param[in] archive The archive to read from.
+ * \param[out] data Pointer to memory that receives the binary data.
+ * \param[out] size Pointer to memory that receives the size of the blob.
+ */
 UStatus
 u_application_archive_read_bytes(
-	UApplicationArchive *archive,
-	const intptr_t *data,
-	size_t size);
+    UApplicationArchive *archive,
+    const intptr_t *data,
+    size_t size);
 
 #endif /* UBUNTU_APPLICATION_ARCHIVE_H_ */

=== modified file 'include/ubuntu/application/description.h'
--- include/ubuntu/application/description.h	2013-05-27 22:14:00 +0000
+++ include/ubuntu/application/description.h	2013-07-05 16:37:30 +0000
@@ -14,7 +14,7 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
  * Authored by: Ricardo Mendoza <[e-mail]>
- *              Thomas Voß <[e-mail]>           
+ *              Thomas Voß <[e-mail]>
  */
 
 #ifndef UBUNTU_APPLICATION_DESCRIPTION_H_
@@ -27,33 +27,71 @@
 extern "C" {
 #endif
 
+    /**
+     * \brief Encapsulates properties of an application instance.
+     * \ingroup application_support
+     */
     typedef void UApplicationDescription;
-    
+
+    /**
+     * \brief Creates a new instance of application description.
+     * \ingroup application_support
+     * \returns A new application description instance or NULL if not enough memory is available.
+     */
     UApplicationDescription*
     u_application_description_new();
-    
+
+    /**
+     * \brief Destroys an instance of application description and releases all resources.
+     * \ingroup application_support
+     * \param[in] desc The instance to be destroyed.
+     */
     void
     u_application_description_destroy(
-    	UApplicationDescription *desc);
-    
+        UApplicationDescription *desc);
+
+    /**
+     * \brief Sets the application id contained in the description instance.
+     * \ingroup application_support
+     * \param[in] desc The application description instance, must not be NULL.
+     * \param[in] id The new application id, must not be NULL.
+     */
     void
     u_application_description_set_application_id(
-    	UApplicationDescription *desc,
-    	UApplicationId *id);
-    
-    UApplicationId* 
+        UApplicationDescription *desc,
+        UApplicationId *id);
+
+    /**
+     * \brief Queries the application id contained in the description instance.
+     * \ingroup application_support
+     * \returns The app id contained in the instance.
+     * \param[in] desc The application description instance, must not be NULL.
+     */
+    UApplicationId*
     u_application_description_get_application_id(
-    	UApplicationDescription *desc);
-    
+        UApplicationDescription *desc);
+
+    /**
+     * \brief Sets the application lifecycle delegate
+     * \ingroup application_support
+     * \param[in] desc The application description instance, must not be NULL.
+     * \param[in] lifecycle_delegate The new lifecycle delegate, must not be NULL.
+     */
     void
     u_application_description_set_application_lifecycle_delegate(
-    	UApplicationDescription *desc,
-    	UApplicationLifecycleDelegate *lifecycle_delegate);
-    
-    UApplicationLifecycleDelegate* 
+        UApplicationDescription *desc,
+        UApplicationLifecycleDelegate *lifecycle_delegate);
+
+    /**
+     * \brief Queries the application lifecycle delegate
+     * \ingroup application_support
+     * \returns The application lifecycle delegate contained in the description instance.
+     * \param[in] desc The application description instance, must not be NULL.
+     */
+    UApplicationLifecycleDelegate*
     u_application_description_get_application_lifecycle_delegate(
-    	UApplicationDescription *desc);
-   
+        UApplicationDescription *desc);
+
 #ifdef __cplusplus
 }
 #endif

=== modified file 'include/ubuntu/application/id.h'
--- include/ubuntu/application/id.h	2013-06-04 22:08:07 +0000
+++ include/ubuntu/application/id.h	2013-07-05 16:37:30 +0000
@@ -14,7 +14,7 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
  * Authored by: Ricardo Mendoza <[e-mail]>
- *              Thomas Voß <[e-mail]>           
+ *              Thomas Voß <[e-mail]>
  */
 
 #ifndef UBUNTU_APPLICATION_ID_H_
@@ -26,21 +26,43 @@
 extern "C" {
 #endif
 
+    /**
+     * \brief An opaque type describing an application ID.
+     * \ingroup application_support
+     */
     typedef void UApplicationId;
-    
+
+    /**
+     * \brief Creates a new application ID from an existing string.
+     * \ingroup application_support
+     * \param[in] string The string containing the application ID.
+     * \param[in] size The size of the string.
+     */
     UApplicationId*
     u_application_id_new_from_stringn(
-    	const char *string, 
-    	size_t size);
-    
+        const char *string,
+        size_t size);
+
+    /**
+     * \brief Destroy the supplied application ID instance.
+     * \ingroup application_support
+     * \param[in] id The instance to be destroyed.
+     */
     void
     u_application_id_destroy(UApplicationId *id);
-    
+
+    /**
+     * \brief Compares two application ID instances.
+     * \ingroup application_support
+     * \returns -1 iff lhs < rhs, 0 iff lhs == rhs, 1 iff lhs > rhs.
+     * \param[in] lhs The left-hand-side id to be compared.
+     * \param[in] rhs The right-hand-side id to be compared.
+     */
     int
     u_application_id_compare(
-    	UApplicationId *lhs,
-    	UApplicationId *rhs);
-       
+        UApplicationId *lhs,
+        UApplicationId *rhs);
+
 #ifdef __cplusplus
 }
 #endif

=== modified file 'include/ubuntu/application/instance.h'
--- include/ubuntu/application/instance.h	2013-05-27 22:14:00 +0000
+++ include/ubuntu/application/instance.h	2013-07-05 16:37:30 +0000
@@ -14,7 +14,7 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
  * Authored by: Ricardo Mendoza <[e-mail]>
- *              Thomas Voß <[e-mail]>           
+ *              Thomas Voß <[e-mail]>
  */
 
 #ifndef UBUNTU_APPLICATION_INSTANCE_H_
@@ -27,31 +27,65 @@
 extern "C" {
 #endif
 
+    /** \defgroup application_support Functions and types to support application development. */
+
+    /**
+     * \brief Opaque type describing an application instance.
+     * \ingroup application_support
+     * An application instance encapsulates the event loop of an app.
+     */
     typedef void UApplicationInstance;
-    
+
+    /**
+     * \brief Creates a new application instance with a reference count of 1.
+     * \ingroup application_support
+     * \returns A new application instance or NULL in case of low-memory.
+     * \param[in] desc A description object, must not be NULL.
+     * \param[in] options An options object, must not be NULL.
+     */
     UApplicationInstance*
     u_application_instance_new_from_description_with_options(
-    	UApplicationDescription *desc,
-    	UApplicationOptions *options);
-    
+        UApplicationDescription *desc,
+        UApplicationOptions *options);
+
+    /**
+     * \brief Increments the reference count of an application instance.
+     * \ingroup application_support
+     * \param[in] instance The instance to increment the reference count for.
+     */
     void
     u_application_instance_ref(
-    	UApplicationInstance *instance);
-    
+        UApplicationInstance *instance);
+
+    /**
+     * \brief Decrements the reference count of an application instance and releases all resources held by the object if the reference count reaches 0.
+     * \ingroup application_support
+     * \param[in] instance The instance to decrement the reference count for.
+     */
     void
     u_application_instance_unref(
-    	UApplicationInstance *instance);
-    
+        UApplicationInstance *instance);
+
+    /**
+     * \brief Destroys the application instance and releases all its resources.
+     * \ingroup application_support
+     * \param[in] instance The instance to be destroyed.
+     */
     void
     u_application_instance_destroy(
-    	UApplicationInstance *instance);
-    
+        UApplicationInstance *instance);
+
+    /**
+     * \brief Executes the event loop of the application instance
+     * \ingroup application_support
+     * \param[in] instance The instance to be executed.
+     */
     void
     u_application_instance_run(
-    	UApplicationInstance *instance);
+        UApplicationInstance *instance);
 
 #ifdef __cplusplus
 }
 #endif
-    
+
 #endif /* UBUNTU_APPLICATION_INSTANCE_H_ */

=== modified file 'include/ubuntu/application/lifecycle_delegate.h'
--- include/ubuntu/application/lifecycle_delegate.h	2013-05-27 21:49:05 +0000
+++ include/ubuntu/application/lifecycle_delegate.h	2013-07-05 16:37:30 +0000
@@ -14,7 +14,7 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
  * Authored by: Ricardo Mendoza <[e-mail]>
- *              Thomas Voß <[e-mail]>           
+ *              Thomas Voß <[e-mail]>
  */
 
 #ifndef UBUNTU_APPLICATION_LIFECYCLE_DELEGATE_H_
@@ -26,55 +26,127 @@
 #ifdef __cplusplus
 extern "C" {
 #endif
-    
+
+    /**
+     * \brief Prototype for the callback that is invoked whenever the app has been resumed.
+     * \ingroup application_support
+     * \param[in] options Application instance options
+     * \param[in] context The callback context as specified by the application
+     */
     typedef void (*u_on_application_resumed)(const UApplicationOptions *options, void *context);
+    /**
+     * \brief Prototype for the callback that is invoked whenever the app is about to be stopped.
+     * Applications can serialize their state to the supplied archive.
+     * \ingroup application_support
+     */
     typedef void (*u_on_application_about_to_stop)(UApplicationArchive *archive, void *context);
-    
+
+    /**
+     * \brief Opaque type encapsulating all app-specific callback functions.
+     * \ingroup application_support
+     */
     typedef void UApplicationLifecycleDelegate;
-    
+
+    /**
+     * \brief Creates a new instance of the lifecycle delegate with an initial refernce count of 1.
+     * \ingroup application_support
+     * \returns A new instance of the lifecycle delegate or NULL if no memory is available.
+     */
     UApplicationLifecycleDelegate*
     u_application_lifecycle_delegate_new();
-    
+
+    /**
+     * \brief Destroys an instance of the lifecycle delegate and releases all of its resources.
+     * \ingroup application_support
+     * \param[in] delegate The instance to be destroyed.
+     */
     void
     u_application_lifecycle_delegate_destroy(
         UApplicationLifecycleDelegate *delegate);
-    
+
+    /**
+     * \brief Increments the reference count of the supplied lifecycle delegate.
+     * \ingroup application_support
+     * \param[in] delegate The lifecycle delegate to increment the reference count for.
+     */
     void
     u_application_lifecycle_delegate_ref(
         UApplicationLifecycleDelegate *delegate);
-    
+
+    /**
+     * \brief Decrements the reference count of the supplied lifecycle delegate and destroys it if the count reaches 0.
+     * \ingroup application_support
+     * \param[in] delegate The lifecycle delegate to decrement the reference count for.
+     */
     void
     u_application_lifecycle_delegate_unref(
         UApplicationLifecycleDelegate *delegate);
-    
+
+    /**
+     * \brief Sets the resumed cb for the supplied delegate.
+     * \ingroup application_support
+     * \param[in] delegate The lifecycle delegate to adjust the cb for.
+     * \param[in] cb The new callback to be invoked whenever the app resumes.
+     */
     void
     u_application_lifecycle_delegate_set_application_resumed_cb(
         UApplicationLifecycleDelegate *delegate,
         u_on_application_resumed cb);
-    
+
+    /**
+     * \brief Queries the resumed cb from the supplied delegate.
+     * \ingroup application_support
+     * \returns The callback to be invoked whenever the app resumes.
+     * \param[in] delegate The lifecycle delegate to query the callback from.
+     */
     u_on_application_resumed
     u_application_lifecycle_delegate_get_application_resumed_cb(
         UApplicationLifecycleDelegate *delegate);
-    
+
+    /**
+     * \brief Sets the about-to-stop cb for the supplied delegate.
+     * \ingroup application_support
+     * \param[in] delegate The lifecycle delegate to adjust the cb for.
+     * \param[in] cb The new callback to be invoked whenever the app is about to be stopped..
+     */
     void
     u_application_lifecycle_delegate_set_application_about_to_stop_cb(
         UApplicationLifecycleDelegate *delegate,
         u_on_application_about_to_stop cb);
-    
+
+    /**
+     * \brief Queries the about-to-be-stopped cb from the supplied delegate.
+     * \ingroup application_support
+     * \returns The callback to be invoked whenever the app is about to be stopped.
+     * \param[in] delegate The lifecycle delegate to query the callback from.
+     */
     u_on_application_about_to_stop
     u_application_lifecycle_delegate_get_application_about_to_stop_cb(
         UApplicationLifecycleDelegate *delegate);
-    
+
+    /**
+     * \brief Sets the cb context for the supplied delegate.
+     * \ingroup application_support
+     * \param[in] delegate The lifecycle delegate to adjust the context for.
+     * \param[in] context The new cb context.
+     */
     void
     u_application_lifecycle_delegate_set_context(
         UApplicationLifecycleDelegate *delegate,
         void *context);
-    
+
+    /**
+     * \brief Queries the cb context from the supplied delegate.
+     * \ingroup application_support
+     * \returns The context that is passed to callbacks of this delegate.
+     * \param[in] delegate The lifecycle delegate to query the context from.
+     * \param[in] context Unused.
+     */
     void*
     u_application_lifecycle_delegate_get_context(
         UApplicationLifecycleDelegate *delegate,
         void *context);
-    
+
 #ifdef __cplusplus
 }
 #endif

=== modified file 'include/ubuntu/application/operation_mode.h'
--- include/ubuntu/application/operation_mode.h	2013-05-27 21:49:05 +0000
+++ include/ubuntu/application/operation_mode.h	2013-07-05 16:37:30 +0000
@@ -14,16 +14,20 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
  * Authored by: Ricardo Mendoza <[e-mail]>
- *              Thomas Voß <[e-mail]>           
+ *              Thomas Voß <[e-mail]>
  */
 
 #ifndef UBUNTU_APPLICATION_OPERATION_MODE_H_
 #define UBUNTU_APPLICATION_OPERATION_MODE_H_
 
+/**
+ * \brief Describes the different operational modes that an
+ * application can run in.
+ */
 typedef enum
 {
-	U_APPLICATION_FOREGROUND_APP,
-	U_APPLICATION_BACKGROUND_SERVICE
+    U_APPLICATION_FOREGROUND_APP,
+    U_APPLICATION_BACKGROUND_SERVICE
 } UApplicationOperationMode;
 
 #endif /* UBUNTU_APPLICATION_OPERATION_MODE_H_ */

=== modified file 'include/ubuntu/application/options.h'
--- include/ubuntu/application/options.h	2013-05-27 22:14:00 +0000
+++ include/ubuntu/application/options.h	2013-07-05 16:37:30 +0000
@@ -14,7 +14,7 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
  * Authored by: Ricardo Mendoza <[e-mail]>
- *              Thomas Voß <[e-mail]>           
+ *              Thomas Voß <[e-mail]>
  */
 
 #ifndef UBUNTU_APPLICATION_OPTIONS_H_
@@ -26,21 +26,43 @@
 extern "C" {
 #endif
 
+    /**
+     * \brief Encapsulates options as passed to the application.
+     * \ingroup application_support
+     */
     typedef void UApplicationOptions;
-    
+
+    /**
+     * \brief Parses options from the command line.
+     * \ingroup application_support
+     * \returns An options instance if parsing was successful, or 0 otheriwse.
+     * \param[in] argc Number of arguments.
+     * \param[in] argv Arguments.
+     */
     UApplicationOptions*
     u_application_options_new_from_cmd_line(
-    	int argc, 
-    	char** argv);
-    
+        int argc,
+        char** argv);
+
+    /**
+     * \brief Destroys the options object and releases all resources.
+     * \ingroup application_support
+     * \param[in] options The object to be destroyed.
+     */
     void
     u_application_options_destroy(
-    	UApplicationOptions *options);
-    
+        UApplicationOptions *options);
+
+    /**
+     * \brief Queries the operation mode from the supplied options object.
+     * \ingroup application_support
+     * \returns The operation mode as stored in the options object.
+     * \param[in] options The options object to be queried.
+     */
     UApplicationOperationMode
     u_application_options_get_operation_mode(
-    	UApplicationOptions *options);
-       
+        UApplicationOptions *options);
+
 #ifdef __cplusplus
 }
 #endif

=== modified file 'include/ubuntu/application/sensors/accelerometer.h'
--- include/ubuntu/application/sensors/accelerometer.h	2013-05-30 02:03:42 +0000
+++ include/ubuntu/application/sensors/accelerometer.h	2013-07-05 16:37:30 +0000
@@ -26,36 +26,94 @@
 extern "C" {
 #endif
 
+    /**
+     * \brief Opaque type that models the accelerometer.
+     * \ingroup sensor_access
+     */
     typedef void UASensorsAccelerometer;
+
+    /**
+     * \brief Callback type used by applications to subscribe to accelerometer events.
+     * \ingroup sensor_access
+     */
     typedef void (*on_accelerometer_event_cb)(UASAccelerometerEvent* event,
                                               void* context);
 
+    /**
+     * \brief Create a new object for accessing the accelerometer.
+     * \ingroup sensor_access
+     * \returns A new instance or NULL in case of errors.
+     */
     UASensorsAccelerometer*
-    ua_sensors_accelerometer_new(); 
+    ua_sensors_accelerometer_new();
 
+    /**
+     * \brief Enables the supplied accelerometer.
+     * \ingroup sensor_access
+     * \returns U_STATUS_SUCCESS if successful or U_STATUS_ERROR if an error occured.
+     * \param[in] sensor The sensor instance to be enabled.
+     */
     UStatus
     ua_sensors_accelerometer_enable(
         UASensorsAccelerometer* sensor);
 
+    /**
+     * \brief Disables the supplied accelerometer.
+     * \ingroup sensor_access
+     * \returns U_STATUS_SUCCESS if successful or U_STATUS_ERROR if an error occured.
+     * \param[in] sensor The sensor instance to be disabled.
+     */
     UStatus
     ua_sensors_accelerometer_disable(
         UASensorsAccelerometer* sensor);
 
+    /**
+     * \brief Queries the minimum delay between two readings for the supplied sensor.
+     * \ingroup sensor_access
+     * \returns The minimum delay between two readings in [ms].
+     * \param[in] sensor The sensor instance to be queried.
+     */
     uint32_t
     ua_sensors_accelerometer_get_min_delay(
         UASensorsAccelerometer* sensor);
-    
+
+    /**
+     * \brief Queries the minimum value that can be reported by the sensor.
+     * \ingroup sensor_access
+     * \returns The minimum value that can be reported by the sensor.
+     * \param[in] sensor The sensor instance to be queried.
+     */
     float
     ua_sensors_accelerometer_get_min_value(
         UASensorsAccelerometer* sensor);
-  
+
+    /**
+     * \brief Queries the maximum value that can be reported by the sensor.
+     * \ingroup sensor_access
+     * \returns The maximum value that can be reported by the sensor.
+     * \param[in] sensor The sensor instance to be queried.
+     */
     float
     ua_sensors_accelerometer_get_max_value(
         UASensorsAccelerometer* sensor);
- 
+
+    /**
+     * \brief Queries the numeric resolution supported by the sensor
+     * \ingroup sensor_access
+     * \returns The numeric resolution supported by the sensor.
+     * \param[in] sensor The sensor instance to be queried.
+     */
     float
     ua_sensors_accelerometer_get_resolution(
         UASensorsAccelerometer* sensor);
+
+    /**
+     * \brief Set the callback to be invoked whenever a new sensor reading is available.
+     * \ingroup sensor_access
+     * \param[in] sensor The sensor instance to associate the callback with.
+     * \param[in] cb The callback to be invoked.
+     * \param[in] ctx The context supplied to the callback invocation.
+     */
     void
     ua_sensors_accelerometer_set_reading_cb(
         UASensorsAccelerometer* sensor,

=== modified file 'include/ubuntu/application/sensors/event/accelerometer.h'
--- include/ubuntu/application/sensors/event/accelerometer.h	2013-05-30 02:03:42 +0000
+++ include/ubuntu/application/sensors/event/accelerometer.h	2013-07-05 16:37:30 +0000
@@ -25,20 +25,48 @@
 extern "C" {
 #endif
 
+    /**
+     * \brief Opaque type describing an accelerometer reading.
+     * \ingroup sensor_access
+     */
     typedef void UASAccelerometerEvent;
 
+    /**
+     * \brief Query the timestamp of the sensor reading.
+     * \ingroup sensor_access
+     * \returns The timestamp of the sensor reading in [µs], timebase: monotonic clock.
+     * \param[in] event The reading to be queried.
+     */
     uint64_t
     uas_accelerometer_event_get_timestamp(
         UASAccelerometerEvent* event);
-   
+
+    /**
+     * \brief Query the acceleration in x-axis direction.
+     * \ingroup sensor_access
+     * \returns The acceleration in x-axis direction.
+     * \param[in] event The reading to be queried.
+     */
     float
     uas_accelerometer_event_get_acceleration_x(
         UASAccelerometerEvent* event);
-  
+
+    /**
+     * \brief Query the acceleration in y-axis direction.
+     * \ingroup sensor_access
+     * \returns The acceleration in y-axis direction.
+     * \param[in] event The reading to be queried.
+     */
     float
     uas_accelerometer_event_get_acceleration_y(
         UASAccelerometerEvent* event);
-  
+
+    /**
+     * \brief Query the acceleration in z-axis direction.
+     * \ingroup sensor_access
+     * \returns The acceleration in z-axis direction.
+     * \param[in] event The reading to be queried.
+     */
     float
     uas_accelerometer_event_get_acceleration_z(
         UASAccelerometerEvent* event);

=== modified file 'include/ubuntu/application/sensors/event/light.h'
--- include/ubuntu/application/sensors/event/light.h	2013-05-30 02:03:42 +0000
+++ include/ubuntu/application/sensors/event/light.h	2013-07-05 16:37:30 +0000
@@ -25,12 +25,28 @@
 extern "C" {
 #endif
 
+    /**
+     * \brief Opaque type describing an ambient light sensor reading.
+     * \ingroup sensor_access
+     */
     typedef void UASLightEvent;
 
+    /**
+     * \brief Query the timestamp of the sensor reading.
+     * \ingroup sensor_access
+     * \returns The timestamp of the sensor reading in [µs], timebase: monotonic clock.
+     * \param[in] event The reading to be queried.
+     */
     uint64_t
     uas_light_event_get_timestamp(
         UASLightEvent* event);
-   
+
+    /**
+     * \brief Query the value measured by the ambient light sensor.
+     * \ingroup sensor_access
+     * \returns The ambient light level.
+     * \param[in] event The reading to be queried.
+     */
     float
     uas_light_event_get_light(
         UASLightEvent* event);

=== modified file 'include/ubuntu/application/sensors/event/proximity.h'
--- include/ubuntu/application/sensors/event/proximity.h	2013-05-30 02:03:42 +0000
+++ include/ubuntu/application/sensors/event/proximity.h	2013-07-05 16:37:30 +0000
@@ -25,17 +25,39 @@
 extern "C" {
 #endif
 
+    /**
+     * \brief Useful constants when inspecting readings from the proximity sensor.
+     * \ingroup sensor_access
+     */
     typedef enum {
-        U_PROXIMITY_NEAR = 1,
-        U_PROXIMITY_FAR = 2
-    } UASProximityDistance;
-
+        U_PROXIMITY_NEAR = 1, /**< The reading indicates that something is near the sensor/device. */
+        U_PROXIMITY_FAR = 2 /**< The reading indicates that something is far away from the sensor/device. */
+    } UbuntuApplicationSensorsProximityDistance;
+
+    typedef UbuntuApplicationSensorsProximityDistance UASProximityDistance;
+
+    /**
+     * \brief Opaque type describing an accelerometer reading.
+     * \ingroup sensor_access
+     */
     typedef void UASProximityEvent;
 
+    /**
+     * \brief Query the timestamp of the sensor reading.
+     * \ingroup sensor_access
+     * \returns The timestamp of the sensor reading in [µs], timebase: monotonic clock.
+     * \param[in] event The reading to be queried.
+     */
     uint64_t
     uas_proximity_event_get_timestamp(
         UASProximityEvent* event);
-   
+
+    /**
+     * \brief Query the discrete distance as reported by the proximity sensor.
+     * \ingroup sensor_access
+     * \returns The discrete distance as reported by the proximity sensor.
+     * \param[in] event The reading to be queried.
+     */
     UASProximityDistance
     uas_proximity_event_get_distance(
         UASProximityEvent* event);

=== modified file 'include/ubuntu/application/sensors/light.h'
--- include/ubuntu/application/sensors/light.h	2013-07-05 16:37:30 +0000
+++ include/ubuntu/application/sensors/light.h	2013-07-05 16:37:30 +0000
@@ -26,36 +26,94 @@
 extern "C" {
 #endif
 
+    /**
+     * \brief Opaque type that models the ambient light sensor.
+     * \ingroup sensor_access
+     */
     typedef void UASensorsLight;
+
+    /**
+     * \brief Callback type used by applications to subscribe to ambient light sensor events.
+     * \ingroup sensor_access
+     */
     typedef void (*on_light_event_cb)(UASLightEvent* event,
                                       void* context);
 
+    /**
+     * \brief Create a new object for accessing the ambient light sensor.
+     * \ingroup sensor_access
+     * \returns A new instance or NULL in case of errors.
+     */
     UASensorsLight*
-    ua_sensors_light_new(); 
+    ua_sensors_light_new();
 
+    /**
+     * \brief Enables the supplied ambient light sensor.
+     * \ingroup sensor_access
+     * \returns U_STATUS_SUCCESS if successful or U_STATUS_ERROR if an error occured.
+     * \param[in] sensor The sensor instance to be enabled.
+     */
     UStatus
     ua_sensors_light_enable(
         UASensorsLight* sensor);
 
+    /**
+     * \brief Disables the supplied ambient light sensor.
+     * \ingroup sensor_access
+     * \returns U_STATUS_SUCCESS if successful or U_STATUS_ERROR if an error occured.
+     * \param[in] sensor The sensor instance to be disabled.
+     */
     UStatus
     ua_sensors_light_disable(
         UASensorsLight* sensor);
 
+    /**
+     * \brief Queries the minimum delay between two readings for the supplied sensor.
+     * \ingroup sensor_access
+     * \returns The minimum delay between two readings in [ms].
+     * \param[in] sensor The sensor instance to be queried.
+     */
     uint32_t
     ua_sensors_light_get_min_delay(
         UASensorsLight* sensor);
-    
+
+    /**
+     * \brief Queries the minimum value that can be reported by the sensor.
+     * \ingroup sensor_access
+     * \returns The minimum value that can be reported by the sensor.
+     * \param[in] sensor The sensor instance to be queried.
+     */
     float
     ua_sensors_light_get_min_value(
         UASensorsLight* sensor);
-  
+
+    /**
+     * \brief Queries the maximum value that can be reported by the sensor.
+     * \ingroup sensor_access
+     * \returns The maximum value that can be reported by the sensor.
+     * \param[in] sensor The sensor instance to be queried.
+     */
     float
     ua_sensors_light_get_max_value(
         UASensorsLight* sensor);
- 
+
+    /**
+     * \brief Queries the numeric resolution supported by the sensor
+     * \ingroup sensor_access
+     * \returns The numeric resolution supported by the sensor.
+     * \param[in] sensor The sensor instance to be queried.
+     */
     float
     ua_sensors_light_get_resolution(
         UASensorsLight* sensor);
+
+    /**
+     * \brief Set the callback to be invoked whenever a new sensor reading is available.
+     * \ingroup sensor_access
+     * \param[in] sensor The sensor instance to associate the callback with.
+     * \param[in] cb The callback to be invoked.
+     * \param[in] ctx The context supplied to the callback invocation.
+     */
     void
     ua_sensors_light_set_reading_cb(
         UASensorsLight* sensor,

=== modified file 'include/ubuntu/application/sensors/proximity.h'
--- include/ubuntu/application/sensors/proximity.h	2013-05-30 02:03:42 +0000
+++ include/ubuntu/application/sensors/proximity.h	2013-07-05 16:37:30 +0000
@@ -26,36 +26,94 @@
 extern "C" {
 #endif
 
+    /**
+     * \brief Opaque type that models the proximity sensor.
+     * \ingroup sensor_access
+     */
     typedef void UASensorsProximity;
+
+    /**
+     * \brief Callback type used by applications to subscribe to proximity sensor events.
+     * \ingroup sensor_access
+     */
     typedef void (*on_proximity_event_cb)(UASProximityEvent* event,
                                           void* context);
 
+    /**
+     * \brief Create a new object for accessing the proximity sensor.
+     * \ingroup sensor_access
+     * \returns A new instance or NULL in case of errors.
+     */
     UASensorsProximity*
-    ua_sensors_proximity_new(); 
+    ua_sensors_proximity_new();
 
+    /**
+     * \brief Enables the supplied proximity sensor.
+     * \ingroup sensor_access
+     * \returns U_STATUS_SUCCESS if successful or U_STATUS_ERROR if an error occured.
+     * \param[in] sensor The sensor instance to be enabled.
+     */
     UStatus
     ua_sensors_proximity_enable(
         UASensorsProximity* sensor);
 
+    /**
+     * \brief Disables the supplied proximity sensor.
+     * \ingroup sensor_access
+     * \returns U_STATUS_SUCCESS if successful or U_STATUS_ERROR if an error occured.
+     * \param[in] sensor The sensor instance to be disabled.
+     */
     UStatus
     ua_sensors_proximity_disable(
         UASensorsProximity* sensor);
 
+    /**
+     * \brief Queries the minimum delay between two readings for the supplied sensor.
+     * \ingroup sensor_access
+     * \returns The minimum delay between two readings in [ms].
+     * \param[in] sensor The sensor instance to be queried.
+     */
     uint32_t
     ua_sensors_proximity_get_min_delay(
         UASensorsProximity* sensor);
-    
+
+    /**
+     * \brief Queries the minimum value that can be reported by the sensor.
+     * \ingroup sensor_access
+     * \returns The minimum value that can be reported by the sensor.
+     * \param[in] sensor The sensor instance to be queried.
+     */
     float
     ua_sensors_proximity_get_min_value(
         UASensorsProximity* sensor);
-  
+
+    /**
+     * \brief Queries the maximum value that can be reported by the sensor.
+     * \ingroup sensor_access
+     * \returns The maximum value that can be reported by the sensor.
+     * \param[in] sensor The sensor instance to be queried.
+     */
     float
     ua_sensors_proximity_get_max_value(
         UASensorsProximity* sensor);
- 
+
+    /**
+     * \brief Queries the numeric resolution supported by the sensor
+     * \ingroup sensor_access
+     * \returns The numeric resolution supported by the sensor.
+     * \param[in] sensor The sensor instance to be queried.
+     */
     float
     ua_sensors_proximity_get_resolution(
         UASensorsProximity* sensor);
+
+    /**
+     * \brief Set the callback to be invoked whenever a new sensor reading is available.
+     * \ingroup sensor_access
+     * \param[in] sensor The sensor instance to associate the callback with.
+     * \param[in] cb The callback to be invoked.
+     * \param[in] ctx The context supplied to the callback invocation.
+     */
     void
     ua_sensors_proximity_set_reading_cb(
         UASensorsProximity* sensor,

=== modified file 'include/ubuntu/status.h'
--- include/ubuntu/status.h	2013-05-30 02:03:42 +0000
+++ include/ubuntu/status.h	2013-07-05 16:37:30 +0000
@@ -20,10 +20,15 @@
 #ifndef UBUNTU_STATUS_H_
 #define UBUNTU_STATUS_H_
 
+/**
+ * \brief Indicates the status of an operation.
+ */
 typedef enum
 {
-	U_STATUS_SUCCESS,
-    U_STATUS_ERROR
-} UStatus;
+    U_STATUS_SUCCESS, ///< Operation finished successfully.
+    U_STATUS_ERROR ///< Operation finished with an error.
+} UbuntuStatus;
+
+typedef UbuntuStatus UStatus;
 
 #endif /* UBUNTU_STATUS_H_ */

=== modified file 'include/ubuntu/unit.h'
--- include/ubuntu/unit.h	2013-05-27 17:09:02 +0000
+++ include/ubuntu/unit.h	2013-07-05 16:37:30 +0000
@@ -20,13 +20,16 @@
 #ifndef UBUNTU_UNIT_H_
 #define UBUNTU_UNIT_H_
 
+/**
+ * \brief Describes units known to the platform integration layer.
+ */
 typedef enum
 {
-	U_DEGREE,
-	U_METER,
-	U_SECOND,
-	U_METER_PER_SECOND,
-	U_MICRO_TESLA
+    U_DEGREE,
+    U_METER,
+    U_SECOND,
+    U_METER_PER_SECOND,
+    U_MICRO_TESLA
 } UbuntuUnit;
 
 typedef UbuntuUnit UUnit;