Some initial Doxygen-based documentation for the API

2 files changed, 78 insertions, 0 deletions

diff --git a/lib/apiaction.php b/lib/apiaction.php
index d5580abd3..f206f1d5c 100644
--- a/lib/apiaction.php
+++ b/lib/apiaction.php
@@ -32,6 +32,66 @@
  * @link      http://status.net/
  */
 
+/* External API usage documentation. Please update when you change how the API works. */
+
+/*! @mainpage StatusNet REST API
+
+    @section Introduction
+
+    Some explanatory text about the API would be nice.
+
+    @section API Methods
+
+    @subsection timelinesmethods_sec Timeline Methods
+
+    @li @ref friendstimeline
+
+    @subsection statusmethods_sec Status Methods
+
+    @li @ref statusesupdate
+
+    @subsection usermethods_sec User Methods
+
+    @subsection directmessagemethods_sec Direct Message Methods
+
+    @subsection friendshipmethods_sec Friendship Methods
+
+    @subsection socialgraphmethods_sec Social Graph Methods
+
+    @subsection accountmethods_sec Account Methods
+
+    @subsection favoritesmethods_sec Favorites Methods
+
+    @subsection blockmethods_sec Block Methods
+
+    @subsection oauthmethods_sec OAuth Methods
+
+    @subsection helpmethods_sec Help Methods
+
+    @subsection groupmethods_sec Group Methods
+
+    @page apiroot API Root
+
+    The URLs for methods referred to in this API documentation are
+    relative to the StatusNet API root. The API root is determined by the
+    site's @b server and @b path variables, which are generally specified
+    in config.php. For example:
+
+    @code
+    $config['site']['server'] = 'example.org';
+    $config['site']['path'] = 'statusnet'
+    @endcode
+
+    The pattern for a site's API root is: @c protocol://server/path/api E.g:
+
+    @c http://example.org/statusnet/api
+
+    The @b path can be empty.  In that case the API root would simply be:
+
+    @c http://example.org/api
+
+*/
+
 if (!defined('STATUSNET')) {
     exit(1);
 }
diff --git a/lib/apiauth.php b/lib/apiauth.php
index d6ad7e021..8c3998888 100644
--- a/lib/apiauth.php
+++ b/lib/apiauth.php
@@ -34,6 +34,24 @@
  * @link      http://status.net/
  */
 
+/* External API usage documentation. Please update when you change how this method works. */
+
+/*! @page authentication Authentication
+
+    StatusNet supports HTTP Basic Authentication and OAuth for API calls.
+
+    @warning Currently, users who have created accounts without setting a
+    password via OpenID, Facebook Connect, etc., cannot use the API until
+    they set a password with their account settings panel.
+
+    @section HTTP Basic Auth
+
+
+
+    @section OAuth
+
+*/
+
 if (!defined('STATUSNET')) {
     exit(1);
 }