Provide basic Conduit documentation.

.divinerconfig

@@ -12,6 +12,7 @@
     "diffusion" : "Diffusion (Repository Browser)",
     "maniphest" : "Maniphest (Task Tracking)",
     "herald" : "Herald (Notifications)",
+    "conduit" : "Conduit (Phabricator HTTP API)",
     "celerity" : "Celerity (CSS/JS Management)",
     "aphront" : "Aphront (Web Stack)",
     "console" : "DarkConsole (Debugging Console)",

src/applications/conduit/controller/api/PhabricatorConduitAPIController.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class PhabricatorConduitAPIController
   extends PhabricatorConduitController {
 

src/applications/conduit/controller/base/PhabricatorConduitController.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 abstract class PhabricatorConduitController extends PhabricatorController {
 
   public function buildStandardPageResponse($view, array $data) {

src/applications/conduit/controller/console/PhabricatorConduitConsoleController.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class PhabricatorConduitConsoleController
   extends PhabricatorConduitController {
 

src/applications/conduit/controller/log/PhabricatorConduitLogController.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class PhabricatorConduitLogController extends PhabricatorConduitController {
 
   public function processRequest() {

src/applications/conduit/controller/token/PhabricatorConduitTokenController.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class PhabricatorConduitTokenController extends PhabricatorConduitController {
 
   public function processRequest() {

src/applications/conduit/method/base/ConduitAPIMethod.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 abstract class ConduitAPIMethod {
 
   abstract public function getMethodDescription();

src/applications/conduit/method/conduit/connect/ConduitAPI_conduit_connect_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_conduit_connect_Method extends ConduitAPIMethod {
 
   public function shouldRequireAuthentication() {

src/applications/conduit/method/conduit/getcertificate/ConduitAPI_conduit_getcertificate_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_conduit_getcertificate_Method extends ConduitAPIMethod {
 
   public function shouldRequireAuthentication() {

src/applications/conduit/method/conduit/ping/ConduitAPI_conduit_ping_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_conduit_ping_Method extends ConduitAPIMethod {
 
   public function shouldRequireAuthentication() {

src/applications/conduit/method/daemon/launched/ConduitAPI_daemon_launched_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_daemon_launched_Method extends ConduitAPIMethod {
 
   public function shouldRequireAuthentication() {

src/applications/conduit/method/daemon/log/ConduitAPI_daemon_log_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_daemon_log_Method extends ConduitAPIMethod {
 
   public function shouldRequireAuthentication() {

src/applications/conduit/method/differential/creatediff/ConduitAPI_differential_creatediff_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_creatediff_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/differential/createrevision/ConduitAPI_differential_createrevision_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_createrevision_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/differential/find/ConduitAPI_differential_find_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_find_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/differential/getalldiffs/ConduitAPI_differential_getalldiffs_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_getalldiffs_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/differential/getcommitmessage/ConduitAPI_differential_getcommitmessage_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_getcommitmessage_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/differential/getcommitpaths/ConduitAPI_differential_getcommitpaths_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_getcommitpaths_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/differential/getdiff/ConduitAPI_differential_getdiff_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_getdiff_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/differential/getrevision/ConduitAPI_differential_getrevision_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_getrevision_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/differential/getrevisionfeedback/ConduitAPI_differential_getrevisionfeedback_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_getrevisionfeedback_Method
   extends ConduitAPIMethod {
 

src/applications/conduit/method/differential/markcommitted/ConduitAPI_differential_markcommitted_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_markcommitted_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/differential/parsecommitmessage/ConduitAPI_differential_parsecommitmessage_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_parsecommitmessage_Method
   extends ConduitAPIMethod {
 

src/applications/conduit/method/differential/setdiffproperty/ConduitAPI_differential_setdiffproperty_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_setdiffproperty_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/differential/updaterevision/ConduitAPI_differential_updaterevision_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_updaterevision_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/differential/updatetaskrevisionassoc/ConduitAPI_differential_updatetaskrevisionassoc_Method.php

@@ -16,8 +16,12 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_updatetaskrevisionassoc_Method
   extends ConduitAPIMethod {
+
   public function getMethodDescription() {
     return "Given a task together with its original and new associated ".
       "revisions, update the revisions for their attached_tasks.";

src/applications/conduit/method/differential/updateunitresults/ConduitAPI_differential_updateunitresults_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_differential_updateunitresults_Method
 extends ConduitAPIMethod {
 

src/applications/conduit/method/diffusion/getcommits/ConduitAPI_diffusion_getcommits_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_diffusion_getcommits_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/diffusion/getrecentcommitsbypath/ConduitAPI_diffusion_getrecentcommitsbypath_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_diffusion_getrecentcommitsbypath_Method
   extends ConduitAPIMethod {
 

src/applications/conduit/method/file/download/ConduitAPI_file_download_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_file_download_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/file/upload/ConduitAPI_file_upload_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_file_upload_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/maniphest/info/ConduitAPI_maniphest_info_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_maniphest_info_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/paste/info/ConduitAPI_paste_info_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_paste_info_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/path/getowners/ConduitAPI_path_getowners_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_path_getowners_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/user/find/ConduitAPI_user_find_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_user_find_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/method/user/whoami/ConduitAPI_user_whoami_Method.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPI_user_whoami_Method extends ConduitAPIMethod {
 
   public function getMethodDescription() {

src/applications/conduit/protocol/exception/ConduitException.php

@@ -16,5 +16,8 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitException extends Exception {
 }

src/applications/conduit/protocol/request/ConduitAPIRequest.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class ConduitAPIRequest {
 
   protected $params;

src/applications/conduit/storage/base/PhabricatorConduitDAO.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 abstract class PhabricatorConduitDAO extends PhabricatorLiskDAO {
 
   public function getApplicationName() {

src/applications/conduit/storage/connectionlog/PhabricatorConduitConnectionLog.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class PhabricatorConduitConnectionLog extends PhabricatorConduitDAO {
 
   protected $client;

src/applications/conduit/storage/methodcalllog/PhabricatorConduitMethodCallLog.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class PhabricatorConduitMethodCallLog extends PhabricatorConduitDAO {
 
   protected $connectionID;

src/applications/conduit/storage/token/PhabricatorConduitCertificateToken.php

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * @group conduit
+ */
 class PhabricatorConduitCertificateToken extends PhabricatorConduitDAO {
 
   protected $userPHID;

src/docs/technical/conduit.diviner

@@ -0,0 +1,57 @@
+@title Conduit Technical Documentation
+@group conduit
+
+Technical overview of the Conduit API.
+
+= Overview =
+
+Conduit is an informal mechanism for transferring ad-hoc JSON blobs around on
+the internet.
+
+Theoretically, it provides an API to Phabricator so external scripts (including
+scripts written in other languages) can interface with the applications in the
+Phabricator suite. It technically does this, sort of, but it is unstable and
+incomplete so you should keep your expectations very low if you choose to build
+things on top of it.
+
+NOTE: Hopefully, this should improve over time, but making Conduit more robust
+isn't currently a major project priority because there isn't much demand for it
+outside of internal scripts. If you want to use Conduit to build things on top
+of Phabricator, let us know so we can adjust priorities.
+
+Conduit provides an authenticated HTTP API for Phabricator. It is informal and
+extremely simple: you post a JSON blob and you get a JSON blob back. You can
+access Conduit in PHP with @{class@libphutil:ConduitClient}, or in any language
+by executing ##arc call-conduit method## (see ##arc help call-conduit## for
+more information). You can see and test available methods at ##/conduit/## in
+the web interface.
+
+Arcanist is implemented using Conduit, and @{class:PhabricatorIRCBot} is
+intended as a practical example of how to write a program which interfaces with
+Phabricator over Conduit.
+
+= Class Relationships =
+
+The primary Conduit workflow is exposed at ##/api/##, which routes to
+@{class:PhabricatorConduitAPIController}. This controller builds a
+@{class:ConduitAPIRequest} representing authentication information and POST
+parameters, instantiates an appropriate subclass of @{class:ConduitAPIMethod},
+and passes the request to it. Subclasses of @{class:ConduitAPIMethod} implement
+the actual methods which Conduit exposes.
+
+Conduit calls which fail throw @{class:ConduitException}, which the controller
+handles.
+
+There is a web interface for viewing and testing Conduit called the "Conduit
+Console", implemented by @{class:PhabricatorConduitConsoleController} at
+##/conduit/##.
+
+A log of connections and calls is stored by
+@{class:PhabriatorConduitConnectionLog} and
+@{class:PhabricatorConduitMethodCallLog}, and can be accessed on the web via
+@{class:PhabricatorConduitLogController} at ##/conduit/log/##.
+
+Conduit provides a token-based handshake mechanism used by
+##arc install-certificate## at ##/conduit/token/##, implemented by
+@{class:PhabricatorConduitTokenController} which stores generated tokens using
+@{class:PhabricatorConduitCertificateToken}.

src/storage/queryfx/queryfx.php

@@ -57,6 +57,9 @@ function queryfx_one($conn, $sql/*, ... */) {
   return null;
 }
 
+/**
+ * @group storage
+ */
 function vqueryfx_all($conn, $sql, array $argv) {
   array_unshift($argv, $conn, $sql);
   call_user_func_array('queryfx', $argv);