From 0ca80f78fbb07ebaaa1509c65021eb5f26cf5c99 Mon Sep 17 00:00:00 2001
From: Brion Vibber <brion@pobox.com>
Date: Tue, 15 Dec 2009 18:27:03 -0500
Subject: [PATCH] Add doc comments listing the array parameters for
 User::register() and Notice::saveNew()

---
 classes/Notice.php | 29 +++++++++++++++++++++++++++++
 classes/User.php   | 21 +++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/classes/Notice.php b/classes/Notice.php
index 2205279e8f..7651d8bd50 100644
--- a/classes/Notice.php
+++ b/classes/Notice.php
@@ -175,6 +175,35 @@ class Notice extends Memcached_DataObject
         }
     }
 
+    /**
+     * Save a new notice and push it out to subscribers' inboxes.
+     * Poster's permissions are checked before sending.
+     *
+     * @param int $profile_id Profile ID of the poster
+     * @param string $content source message text; links may be shortened
+     *                        per current user's preference
+     * @param string $source source key ('web', 'api', etc)
+     * @param array $options Associative array of optional properties:
+     *              string 'created' timestamp of notice; defaults to now
+     *              int 'is_local' source/gateway ID, one of:
+     *                  Notice::LOCAL_PUBLIC    - Local, ok to appear in public timeline
+     *                  Notice::REMOTE_OMB      - Sent from a remote OMB service;
+     *                                            hide from public timeline but show in
+     *                                            local "and friends" timelines
+     *                  Notice::LOCAL_NONPUBLIC - Local, but hide from public timeline
+     *                  Notice::GATEWAY         - From another non-OMB service;
+     *                                            will not appear in public views
+     *              float 'lat' decimal latitude for geolocation
+     *              float 'lon' decimal longitude for geolocation
+     *              int 'location_id' geoname identifier
+     *              int 'location_ns' geoname namespace to interpret location_id
+     *              int 'reply_to'; notice ID this is a reply to
+     *              int 'repeat_of'; notice ID this is a repeat of
+     *              string 'uri' permalink to notice; defaults to local notice URL
+     *
+     * @return Notice
+     * @throws ClientException
+     */
     static function saveNew($profile_id, $content, $source, $options=null) {
         $defaults = array('uri' => null,
                           'reply_to' => null,
diff --git a/classes/User.php b/classes/User.php
index c62314d500..ae709b46b6 100644
--- a/classes/User.php
+++ b/classes/User.php
@@ -180,6 +180,27 @@ class User extends Memcached_DataObject
         return $result;
     }
 
+    /**
+     * Register a new user account and profile and set up default subscriptions.
+     * If a new-user welcome message is configured, this will be sent.
+     *
+     * @param array $fields associative array of optional properties
+     *              string 'bio'
+     *              string 'email'
+     *              bool 'email_confirmed' pass true to mark email as pre-confirmed
+     *              string 'fullname'
+     *              string 'homepage'
+     *              string 'location' informal string description of geolocation
+     *              float 'lat' decimal latitude for geolocation
+     *              float 'lon' decimal longitude for geolocation
+     *              int 'location_id' geoname identifier
+     *              int 'location_ns' geoname namespace to interpret location_id
+     *              string 'nickname' REQUIRED
+     *              string 'password' (may be missing for eg OpenID registrations)
+     *              string 'code' invite code
+     *              ?string 'uri' permalink to notice; defaults to local notice URL
+     * @return mixed User object or false on failure
+     */
     static function register($fields) {
 
         // MAGICALLY put fields into current scope