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:

Title

<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)	Show volume details
Update (PUT)	Update volume
Delete (DELETE)	Delete volume

Short description

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

Make the short description short. Put extra content into subsequent <para> tags.

Follow this convention for short description text:

Method	Example short description	Do not use
Create (POST)	Creates a volume.	Create a volume. Creates a new volume.
List (GET)	Lists volumes.	Gets a listing of volumes. Prints a listing of volumes. Retrieves a list of volumes.
Show (GET)	Shows volume details. Shows image details. Shows the up time for a specified hypervisor.	Retrieves information about, or Gets information for.
Update (PUT)	Updates volume details.
Delete (DELETE)	Deletes a volume.	Removes a volume. Permanently destroys a volume.