include/nn/ac: Document existing nn_ac functions

include/nn/ac.h

@@ -2,6 +2,8 @@
 
 /**
  * \defgroup nn_ac nn_ac
+ * Auto Connect API, used for managing and connecting to internet connection
+ * profiles.
  */
 
 #include <nn/ac/ac_c.h>

include/nn/ac/ac_c.h

@@ -5,6 +5,7 @@
 /**
  * \defgroup nn_ac_c Auto Connect C API
  * \ingroup nn_ac
+ * C functions for the Auto Connect API
  * @{
  */
 
@@ -12,20 +13,77 @@
 extern "C" {
 #endif
 
+/**
+ * An ID number representing a network configuration. These are the same IDs as
+ * shown in System Settings' Connection List.
+ */
 typedef uint32_t ACConfigId;
 
+/**
+ * Initialise the Auto Connect library. Call this function before any other AC
+ * functions.
+ *
+ * \return
+ * A \link nn_result Result\endlink - see \link NNResult_IsSuccess \endlink
+ * and \link NNResult_IsFailure \endlink.
+ *
+ * \sa
+ * - \link ACFinalize \endlink
+ */
 NNResult
 ACInitialize();
 
+/**
+ * Cleanup the Auto Connect library. Do not call any AC functions (other than
+ * \link ACInitialize \endlink) after calling this function.
+ *
+ * \sa
+ * - \link ACInitialize \endlink
+ */
 void
 ACFinalize();
 
+/**
+ * Gets the default connection configuration id. This is the default as marked
+ * in System Settings.
+ *
+ * \param configId
+ * A pointer to an \link ACConfigId \endlink to write the config ID to. Must not
+ * be \c NULL.
+ *
+ * \return
+ * A \link nn_result Result\endlink - see \link NNResult_IsSuccess \endlink
+ * and \link NNResult_IsFailure \endlink.
+ */
 NNResult
 ACGetStartupId(ACConfigId *configId);
 
+/**
+ * Connects to a network, using the configuration represented by the given
+ * \link ACConfigId \endlink.
+ *
+ * \param configId
+ * The \link ACConfigId \endlink representing the network to connect to.
+ *
+ * \return
+ * A \link nn_result Result\endlink - see \link NNResult_IsSuccess \endlink
+ * and \link NNResult_IsFailure \endlink.
+ */
 NNResult
 ACConnectWithConfigId(ACConfigId configId);
 
+/**
+ * Gets the IP address assosciated with the currently active connection.
+ *
+ * \param ip
+ * A pointer to write the IP address to, in
+ * <a href="https://en.wikipedia.org/wiki/IPv4#Address_representations"
+ * target="_blank">numerical</a> form.
+ *
+ * \return
+ * A \link nn_result Result\endlink - see \link NNResult_IsSuccess \endlink
+ * and \link NNResult_IsFailure \endlink.
+ */
 NNResult
 ACGetAssignedAddress(uint32_t *ip);
 

include/nn/ac/ac_cpp.h

@@ -5,6 +5,7 @@
 /**
  * \defgroup nn_ac_cpp Auto Connect C++ API
  * \ingroup nn_ac
+ * C++ functions for the Auto Connect API (see nn::ac)
  * @{
  */
 
@@ -12,11 +13,24 @@
 
 namespace nn
 {
+/**
+ * Auto Connect API, used for managing and connecting to internet connection
+ * profiles.
+ */
 namespace ac
 {
 
+/**
+ * An ID number representing a network configuration. These are the same IDs as
+ * shown in System Settings' Connection List.
+ */
 typedef uint32_t ConfigIdNum;
 
+/**
+ * C++ linkage for the autoconnect API, see \link nn::ac \endlink for use.
+ * Cafe provides mangled symbols for C++ APIs, so nn::ac is actually static
+ * inline calls to the mangled symbols under nn::ac::detail.
+ */
 namespace detail
 {
 extern "C"
@@ -31,9 +45,16 @@ nn::Result GetAssignedAddress__Q2_2nn2acFPUl(uint32_t *ip);
 } // extern "C"
 } // namespace detail
 
-
 /**
- * Initialise the nn_ac library.
+ * Initialise the Auto Connect library. Call this function before any other nn::ac
+ * functions.
+ *
+ * \return
+ * A \link nn::Result Result\endlink - see \link nn::Result::IsSuccess \endlink
+ * and \link nn::Result::IsFailure \endlink.
+ *
+ * \sa
+ * - \link Finalize \endlink
  */
 static inline nn::Result
 Initialize()
@@ -41,9 +62,12 @@ Initialize()
    return detail::Initialize__Q2_2nn2acFv();
 }
 
-
 /**
- * Finalise the nn_ac library.
+ * Cleanup the Auto Connect library. Do not call any nn::ac functions (other
+ * than \link Initialize \endlink) after calling this function.
+ *
+ * \sa
+ * - \link Initialize \endlink
  */
 static inline void
 Finalize()
@@ -53,7 +77,16 @@ Finalize()
 
 
 /**
- * Get the default connection configuration id.
+ * Gets the default connection configuration id. This is the default as marked
+ * in System Settings.
+ *
+ * \param id
+ * A pointer to an \link ConfigIdNum \endlink to write the config ID to. Must
+ * not be a \c nullptr.
+ *
+ * \return
+ * A \link nn::Result Result\endlink - see \link nn::Result::IsSuccess \endlink
+ * and \link nn::Result::IsFailure \endlink.
  */
 static inline nn::Result
 GetStartupId(ConfigIdNum *id)
@@ -61,9 +94,16 @@ GetStartupId(ConfigIdNum *id)
    return detail::GetStartupId__Q2_2nn2acFPQ3_2nn2ac11ConfigIdNum(id);
 }
 
-
 /**
- * Connect to configuration id.
+ * Connects to a network, using the configuration represented by the given
+ * \link ConfigIdNum \endlink.
+ *
+ * \param id
+ * The \link ConfigIdNum \endlink representing the network to connect to.
+ *
+ * \return
+ * A \link nn::Result Result\endlink - see \link nn::Result::IsSuccess \endlink
+ * and \link nn::Result::IsFailure \endlink.
  */
 static inline nn::Result
 Connect(ConfigIdNum id)
@@ -71,9 +111,17 @@ Connect(ConfigIdNum id)
    return detail::Connect__Q2_2nn2acFQ3_2nn2ac11ConfigIdNum(id);
 }
 
-
 /**
- * Get the IP address of the current connection.
+ * Gets the IP address assosciated with the currently active connection.
+ *
+ * \param ip
+ * A pointer to write the IP address to, in
+ * <a href="https://en.wikipedia.org/wiki/IPv4#Address_representations"
+ * target="_blank">numerical</a> form.
+ *
+ * \return
+ * A \link nn::Result Result\endlink - see \link nn::Result::IsSuccess \endlink
+ * and \link nn::Result::IsFailure \endlink.
  */
 static inline nn::Result
 GetAssignedAddress(uint32_t *ip)