Documentation/WADL conventions

OpenStack Documentation

Documentation Contributor Guide — HowTo for first timers — Building documentation — Speciality Teams — Documentation office hours

WADL style and markup conventions

In progress......

What is WADL?

For information about WADL files, see http://docs.rackspace.com/writers-guide/content/ch_wadl.html.

For complete information about the WADL language, see Web Application Description Language (http://www.w3.org/Submission/wadl/).

Writing style

An API method has the following components:

OpenStack Documentation

Documentation Contributor Guide — HowTo for first timers — Building documentation — Speciality Teams — Documentation office hours

Title

Specify the title for a method as follows:

<method name="GET" id="getVolume">
        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
            title="Show volume details">

Use sentence-style capitalization for the title.

Follow this convention for title text:

Method	Example title
Create (POST)	Create volume
List (GET)	List volumes
Show (GET)	List volume details
Update (PUT)	Update volume
Delete (DELETE)	Delete volume

Short description

List methods (GET)

Short description: Use the text: "Lists available xxx." Do not use "Gets a listing," or "Prints a listing."

Show methods (GET)

Short description: Use the text: "Shows xxx details" or "Shows the xx for a specified xx." Do not use, "Retrieves information about," or "Gets information for." For example: "Shows image details," or "Shows the up time for a specified hypervisor."

Update methods (PUT)

Short description: Use the text: "Updates xxx."

Create methods (POST)

Short description: Use the text: "Creates a xxx." Do not use, "Creates a new xxx." The word "creates" implies a new resource.

Delete methods (DELETE)

Short description: Use the text: "Deletes a xxx," or "Deletes a specified xxx."

Markup

TBD.

---