Selenium Core API Documentation Standard - Selenium

This is a proposed standard for comments attached to Selenium Commands in the Selenium Core API. This documentation standard allows us to automatically generate up-to-date Selenium documentation and to generate language bindings in other languages.

Under this standard, comments would be embedded in the code, in a manner similar to JavaDoc, which is documented here:

http://java.sun.com/j2se/javadoc/writingdoccomments/

It's not precisely identical to JavaDoc, though. In particular, we'd be using only a tiny subset of the JavaDoc supported tags, and the comments would appear inside the method body instead of just outside of the method body. (This is to make the comments easier to find and manipulate in JavaScript.) We'll also include a return type, in order to generate language bindings for strongly-typed languages, and to give end users a hint as to what they'll get back.

Here's an example:

Selenium.prototype.getText = function(locator) {
   /**
    * Get the (trimmed) text of a <i>form</i> element.
    * @param locator an element locator specifying the element whose text
    *   we'll extract
    * @return string the (trimmed) text of the element
    */
   var element = this.page().findElement(locator);
   return getText(element).trim();
};

This method would be translated into the following XML snippet:

<function name="getText">
 	<param name="locator">an element locator specifying the element whose text we'll extract</arg>
 	<comment>Get the (trimmed) text of a <i>form</i> element.</comment>
 	<return type="string">the (trimmed)text of the element</return>
</function>

Which, in turn, might be translated into HTML or source code any way you like.

Like JavaDoc, comments MAY use HTML formatting; the HTML formatting. (However, HTML tags MUST be correctly balanced; HTML tags will NOT be XML-encoded in the XML output.) Furthermore, all of the standard JavaDoc style rules would apply.

We would support only the following two tags (@param and @return). All other JavaDoc-like tags in the inline comment will be ignored.

@param

As per JavaDoc, including style guidelines.

http://java.sun.com/j2se/javadoc/writingdoccomments/#@param

The @param tag is followed by the name (not data type) of the parameter, followed by a description of the parameter. By convention, the first noun in the description is the data type of the parameter. (Articles like "a", "an", and "the" can precede the noun.) An exception is made for the primitive int, where the data type is usually omitted. Additional spaces can be inserted between the name and description so that the descriptions line up in a block. Dashes or other punctuation should not be inserted before the description, as the Javadoc tool inserts one dash.

Parameter names are lowercase by convention. The data type starts with a lowercase letter to indicate an object rather than a class. The description begins with a lowercase letter if it is a phrase (contains no verb), or an uppercase letter if it is a sentence. End the phrase with a period only if another phrase or sentence follows it.

Example:

  * @param ch        the character to be tested
  * @param observer  the image observer to be notified

Do not bracket the name of the parameter after the @param tag with <code>...</code> since Javadoc 1.2 and later automatically do this. (Beginning with 1.4, the name cannot contain any HTML, as Javadoc compares the @param name to the name that appears in the signature and emits a warning if there is any difference.)

When writing the comments themselves, in general, start with a phrase and follow it with sentences if they are needed.

When writing a phrase, do not capitalize and do not end with a period:
```
@param x  the x-coordinate, measured in pixels
```

When writing a phrase followed by a sentence, do not capitalize the phrase, but end it with a period to distinguish it from the start of the next sentence:
```
@param x  the x-coordinate. Measured in pixels.
```

If you prefer starting with a sentence, capitalize it and end it with a period:
```
@param x  Specifies the x-coordinate, measured in pixels.
```

When writing multiple sentences, follow normal sentence rules:
```
@param x  Specifies the x-coordinate. Measured in pixels. 
```

Multiple @param tags should be listed in argument-declaration order. This makes it easier to visually match the list to the declaration.

@return

As per JavaDoc, including style guidelines, except we also include the return type in order to generate proper language bindings for other languages, and to give end users a hint as to what they'll get back.

All and only the following return types are valid:

string
number
boolean
string[]
number[]
boolean[]

http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@return

Omit @return for methods that return void and for constructors; include it for all other methods, even if its content is entirely redundant with the method description. Having an explicit @return tag makes it easier for someone to find the return value quickly. Whenever possible, supply return values for special cases (such as specifying the value returned when an out-of-bounds argument is supplied).

Use the same capitalization and punctuation as you used in @param.