diff --git a/doc/documentation.php b/doc/documentation.php index 7ebca46..ee8d442 100644 --- a/doc/documentation.php +++ b/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() - * - fread()/fwrite() - * - file_get_contents(), stream_get_contents() - * - stat()/fstat() - * - is_readable()/is_writable() - * - And so on (http://us3.php.net/manual/en/ref.filesystem.php). + *- fopen()/fclose() + *- fread()/fwrite() + *- file_get_contents(), stream_get_contents() + *- stat()/fstat() + *- is_readable()/is_writable() + *- 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 IdentityServices class handles authenticating to HP, discovering services, and providing + *-# 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 * 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. - * - Container services are in HPCloud::Storage::ObjectStorage::Container - * - There are two classes for objects: + *- HPCloud::Storage::ObjectStorage is where you will start. + *- Container services are in HPCloud::Storage::ObjectStorage::Container + *- 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 - * - CDN caching of storage - * - Others coming. + *- ObjectStorage + *- CDN caching of storage + *- Others coming. * */ /** diff --git a/doc/oo-tutorial.md b/doc/oo-tutorial.md index 25a231c..bb7ca99 100644 --- a/doc/oo-tutorial.md +++ b/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 diff --git a/doc/style.md b/doc/style.md index 5c84ca4..d174221 100644 --- a/doc/style.md +++ b/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 here 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} here 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 - * 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. - */ +class Pillow { + + function __construct($name, $a2 = NULL, $a3 = NULL) { + + // .... + if (is_string($a2)) { + // Do one thing... + } + elseif (is_object($a2)) { + // Do another thing. + } + } +} +?> +~~~ + +The above quickly degenerates into code that is both slow +(because of the inspection tasks) and difficult to read and use. + +Another option, following Objective-C and Vala, is to create constructor +functions. These are static functions (in PHP, at least) that can build +instances. Constructor functions have signatures like +`Pillow::newFromJSON()` and `Pillow::newFromXML()`. + +*This library uses constructor functions.* Generally, a very basic +constructor is provided for cases where it is needed, but more complex +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.