15.4 How to read the method descriptions

The method descriptions are written on the assumption that the reader has the following in mind while reading them:

• Each method description begins with the signature of its “topic method”.
• In the method description, the phrase “this method” always refers to the topic method.
• Whenever “this method” is the subject of a sentence in the method description, it may be elided, so that, for example,

  This method returns 42.

  becomes

  Returns 42.

• In a time object method, the instance, sometimes called the “self argument”, is always the first argument of the method. In the descriptions of time object methods, references to the base objects of the instance are often left implied. For example, rather than write “the rule with ID id in the base grammar”, we will usually write “the rule with ID id”. References to time objects other than base objects of the instance are always explicitly stated, as are references to multiple time objects.
• If the return type of a method is not void, the last paragraph of its method description is a “return value summary”. The return value summary starts with the label “Return Value”.
• Every method returns in exactly one of three statuses: success, hard failure, or soft failure.
• A return status of hard failure indicates that the method detected a hard failure.
• A method may have several kinds of hard failure, including several kinds of irrecoverable hard failure and several kinds of recoverable hard failure. On return, these can be distinguished by their error codes.
• If a method call hard fails, its error code is that associated with the hard failure. Unless stated otherwise in the return value summary, the error code is set in the base grammar of the method call, and may be accessed with the methods described below. See Error methods.
• If a method allows a recoverable hard failure, this is explicitly stated in its return value summary, along with the associated error code. The method description will state the circumstances under which the recoverable hard failure occurs, and what the application must do to recover.
• A return status of soft failure indicates that the method detected a soft failure.
• Every method has at most one kind of soft failure.
• If a method allows a soft failure, this is explicitly stated in its return value summary, and the method description will state the circumstances under which the soft failure occurs, and what the application must do to recover.
• If a method call soft fails, the value of the error code is unspecified.
• If a method call succeeds, the value of the error code is unspecified.
• A return status of success indicates that the method did not detect any failures.
• If both a hard failure and a soft failure occur, the return status will be hard failure.
• If both a recoverable hard failure and an irrecoverable hard failure occur, the error code will be for an irrecoverable hard failure.
• The behaviors specified for success and soft failure are application behaviors.
• The behaviors specified for hard failures are diagnostic behaviors if an irrecoverable failure occurred, and application behaviors otherwise.