Updated documentation.

doc/documentation.php

@@ -30,7 +30,7 @@
  *
  * (If you are not sure what the "HPCloud Management Console" is, head over to
  * http://build.hpcloud.com. There you will find some articles and videos
- * explaining the HPCloud structure.
+ * explaining the HPCloud structure.)
  *
  * @section where_to_start Where To Start
  *
@@ -38,9 +38,12 @@
  * started with a library. It's better to know where to start. Here's
  * what we suggest:
  *
- * - Connecting and logging in is almost inevitably going to be your first
+ *- There are a few tutorials inside this documentation that will help you
+ *   get started. One explains [Stream Wrappers](@ref streams-tutorial) and
+ *   the other [the library itself](@ref oo-tutorial).
+ *- Connecting and logging in is almost inevitably going to be your first
  *   task. For that, you will want to look at IdentityServices.
- * - ObjectStorage (a.k.a. swift) is our cloud storage system. There are
+ *- ObjectStorage (a.k.a. swift) is our cloud storage system. There are
  *   two ways to use it:
  *   - You can explore the object oriented API, starting with ObjectStorage.
  *   - You can use the PHP stream wrappers to access your object storage. This
@@ -96,12 +99,12 @@
  * HPCloud ObjectStorage service without using any fancy API at all. Use the
  * normal file methods like this:
  *
- * - fopen()/fclose()
+ *- fopen()/fclose()
- * - fread()/fwrite()
+ *- fread()/fwrite()
- * - file_get_contents(), stream_get_contents()
+ *- file_get_contents(), stream_get_contents()
- * - stat()/fstat()
+ *- stat()/fstat()
- * - is_readable()/is_writable()
+ *- is_readable()/is_writable()
- * - And so on (http://us3.php.net/manual/en/ref.filesystem.php).
+ *- And so on (http://us3.php.net/manual/en/ref.filesystem.php).
  *
  * Learn more about this at HPCloud::Storage::ObjectStorage::StreamWrapper.
  *
@@ -148,10 +151,10 @@
  * ?>
  * @endcode
  *
- * -# Our classes use PHP namespaces to organize components. If you've never used
+ *-# Our classes use PHP namespaces to organize components. If you've never used
  *   them before, don't worry. They're easy to get the hang of.
- * -# The Bootstrap class handles setting up HPCloud services. Read about it at HPCloud::Bootstrap.
+ *-# The Bootstrap class handles setting up HPCloud services. Read about it at HPCloud::Bootstrap.
- * -# The IdentityServices class handles authenticating to HP, discovering services, and providing
+ *-# The IdentityServices class handles authenticating to HP, discovering services, and providing
  *   access to your account. HPCloud::Services::IdentityServices explains the details, but here are
  *   a few functions you'll want to know:
  *   - HPCloud::Services::IdentityServices::__construct() tells the object where to connect.
@@ -200,9 +203,9 @@
  * HPCloud::Storage::ObjectStorage account. There are many functions for
  * creating and modifying containers and objects, too.
  *
- * - HPCloud::Storage::ObjectStorage is where you will start.
+ *- HPCloud::Storage::ObjectStorage is where you will start.
- * - Container services are in HPCloud::Storage::ObjectStorage::Container
+ *- Container services are in HPCloud::Storage::ObjectStorage::Container
- * - There are two classes for objects:
+ *- There are two classes for objects:
  *     - HPCloud::Storage::ObjectStorage::Object is for creating new objects.
  *     - HPCloud::Storage::ObjectStorage::RemoteObject provides better network
  *     performance when reading objects.
@@ -230,9 +233,9 @@
  *
  * Services for now and the future:
  *
- * - ObjectStorage
+ *- ObjectStorage
- * - CDN caching of storage
+ *- CDN caching of storage
- * - Others coming.
+ *- Others coming.
  *
  */
 /**

doc/oo-tutorial.md

@@ -68,7 +68,7 @@ do anything really fancy with namespaces.
 **In this document, we sometimes replace the backslash (\) with double
 colons (`::`) so that links are automatically generated.** So
 `\HPCloud\Bootstrap` may appear as HPCloud::Bootstrap. The reason for
-this is [explained elsewhere]().
+this is [explained elsewhere](@ref styleguide).
 
 ## Step 1: Getting the Library
 

doc/style.md

@@ -1,29 +1,137 @@
+Coding and Documentation Style Guide     {#styleguide}
+====================================
+
+This guide explain coding style, coding structure, and documentation
+style.
+
+## TL;DR
+
+- Read the [coding standards](https://github.com/mattfarina/Coding-Standards)
+  to learn why we code the way we do.
+- Read the [doxygen manual](http://www.stack.nl/~dimitri/doxygen)
+  if you're curious about our source code documentation.
+- Two spaces, no tabs.
+- WE LOVE GITHUB ISSUES AND PULL REQUESTS
+
+## Code Style
+
+The code in this package rigidly conforms to a given coding standard.
+The standard we use is published <a href="https://github.com/mattfarina/Coding-Standards">here</a> and is based
+on the Drupal coding standards, the PEAR coding standards, and several
+other popular standards.
+
+Important highlights:
+
+- Indentation uses *two space characters* and no tabs.
+- Variables and class names use CamelCasing (details above).
+
+Please do your best to follow coding standards when submitting patches.
+
+### Object Orientation
+
+We have chosen to give the library a strongly object-oriented flavor.
+However, the stream wrapper integration provides a procudural interface
+to some of the services.
+
+### Design Patterns and Coding Practices
+
+Where applicable, we use established coding patterns and practices. Some
+are PHP specific (like stream wrappers), while most enjoy broader
+industry support.
+
+There are a few things a developer should be aware of:
+
+**Accessors and Mutators**: The naming convention for methods on an
+object are as follows:
+
+- A function that accesses an object's data is a *noun*. Thus, the color
+  of a fictional `Pillow` object may be accessed using
+  `Pillow::color()`.
+- A function that performs an action is verbal, and this includes
+  mutator functions (so-called "setters"). Thus,
+  `Pillow::changeColor()`, `Pillow::setColor()`, and `Pillow::fight()` may
+  all be appropriate mutator names. 
+- Unless a contract (interface or superclass) requires it, we do not ever
+  define "getters".
+
+**Constructor Functions**: PHP does not support method overloading
+(that is, declaring multiple methods with the same name, but different
+signatures). While some languages (viz. Java, C++, C#) allow more than
+one constructor, PHP limits you to just one constructor.
+
+One strategy for working around this is to create constructors that take
+vague or generic parameters, and then perform various inspection tasks
+to figure out what the parameters are:
+
+~~~{.php}
 <?php
-/**
+class Pillow {
- * @file
+
- * Documentation on style.
+  function __construct($name, $a2 = NULL, $a3 = NULL) {
- */
+
-/**
+    // ....
- * @page style Coding and Documentation Style Guide
+    if (is_string($a2)) {
- *
+      // Do one thing...
- * @section style_code Code Style
+    }
- *
+    elseif (is_object($a2)) {
- * The code in this package rigidly conforms to a given coding standard.
+      // Do another thing.
- * The standard we use is published <a href="">here</a> and is based
+    }
- * on the Drupal coding standards, the PEAR coding standards, and several
+  }
- * other popular standards.
+}
- *
+?>
- * @section style_documentation Documentation Style
+~~~
- *
+
- * This project is documented with Doxygen, and the configuration file used
+The above quickly degenerates into code that is both slow
- * is available in ./config.doxy in this project.
+(because of the inspection tasks) and difficult to read and use.
- *
+
- * The following conventions are used:
+Another option, following Objective-C and Vala, is to create constructor
- *
+functions. These are static functions (in PHP, at least) that can build
- * - In documentation, namespaces are separated with double-colon (::) instead of
+instances. Constructor functions have signatures like
- *   backslash characters (\\). This is because backslash characters have
+`Pillow::newFromJSON()` and `Pillow::newFromXML()`.
- *   special meaning to Doxygen, and cannot be used as namespace separators.
+
- * - We use \@retval instead of \@return. This special marker was added to
+*This library uses constructor functions.* Generally, a very basic
- *   Doxygen for languages like PHP where the return type is "optional". We
+constructor is provided for cases where it is needed, but more complex
- *   try to always specify a return type, thus we use retval.
+cases are handled with specialized constructor functions.
- */
+
+**Namespaces**: The library has been divided up into namespaces
+according to the following principles:
+
+- Each broad service category should have a namespace. Currently, the
+  service categories are *Services* and *Storage*.
+  * Services handle computing tasks on behalf of the client.
+  * Storage handles data storage and retrieval
+- Individual services and storage services may have their own namespace
+  if the number of supporting classes requires this.
+- The *Transport* namespace deals with lower-level details that are
+  shared across all services.
+
+Otherwise, we have attempted to keep the namespace relatively shallow.
+
+### Balancing Performance and Elegance
+
+Any network-based library must struggle with the inefficiencies of
+working over a network. This library is no exception. We've done our
+best to straddle the line between keeping load times down and making the
+code simple and elegant. Doubtless we have sometimes failed. Please feel
+free to suggest improvements on either side of the scales.
+
+## Documentation Style
+
+This project is documented with Doxygen, and the configuration file used
+is available in ./config.doxy in this project.
+
+The following conventions are used:
+
+- In documentation, namespaces are separated with double-colon (::) instead of
+  backslash characters (\\). This is because backslash characters have
+  special meaning to Doxygen, and cannot be used as namespace separators.
+- We use \@retval instead of \@return. This special marker was added to
+  Doxygen for languages like PHP where the return type is "optional". We
+  try to always specify a return type, thus we use retval.
+
+### Markdown and Doxygen >= 1.8
+
+Since Doxygen 1.8.0, Doxygen boasts native support for Markdown. Where
+possible, we write documentation in Markdown, which makes it both
+readable in the source code form, and also a fully integrated part of
+the API documentation.