stackforge/openstack-sdk-php
Code Issues Proposed changes

Updated documentation.

Browse Source
This commit is contained in:
Matt Butcher
2012-03-15 15:38:49 -05:00
parent 2e3cb2b5b2
commit 291c1e93f4
3 changed files with 158 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
doc/documentation.php
View File

@@ -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.
*
*/
/**

2
doc/oo-tutorial.md
View File

@@ -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

164
doc/style.md
View File

@@ -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
/**
* @file
* Documentation on style.
*/
/**
* @page style Coding and Documentation Style Guide
*
* @section style_code Code Style
*
* The code in this package rigidly conforms to a given coding standard.
* 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
* 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.