Javascript [Electronic resources] : The Definitive Guide (4th Edition) نسخه متنی

Title and Short Description

Every reference entry begins with a four-part title block like that
above. The entries are alphabetized by title. The short description,
shown below the title, gives you a quick summary of the item
documented in the entry; it can help you quickly decide if
you''''re interested in reading the rest of the page.

Availability

The availability information is shown in the upper-right corner of
the title block. This information tells you which version of
Netscape''''s JavaScript interpreter and Microsoft''''s JScript
interpreter the item (class, method, or property) was introduced in.
If the item has been standardized in ECMAScript, it tells you which
version of the standard introduced it. You can assume that anything
available in one version of JavaScript is also available in later
versions. Note, however, that if this section says the item is
deprecated it may be removed in the future and you should avoid using
it.

Inherits from/Overrides

If a class inherits from a superclass or a method overrides a method
in a superclass, that information is shown in the lower-right corner
of the title block.

As described in Chapter 8, JavaScript classes can
inherit properties and methods from other classes. For example, the
String class inherits from Object, and the RangeError class inherits
from Error, which in turn inherits from Object. When you see this
inheritance information, you may also want to look up the listed
superclasses.

When a method has the same name as a method in a superclass, the
method overrides the superclass''''s method. See
Array.toString( ) for an example.

Constructor

If the reference page documents a class, it usually has a
"Constructor" section that shows you how to use the
constructor method to create instances of the class. Since
constructors are a type of method, the "Constructor"
section looks a lot like the "Synopsis" section of a
method''''s reference page.

Synopsis

Reference pages for functions, methods, and properties have a
"Synopsis" section that shows how you might use the
function, method, or property in your code. For example, the synopsis
for the Array.concat( ) method is:

array.concat(value, ...)

The italic font indicates text that is to
be replaced with something else. array
should be replaced with a variable or JavaScript expression that
holds or evaluates to an array. And value
simply represents an arbitrary value that is to be concatenated to
the array. The ellipsis (...) indicates that this
method can take any number of value
arguments. Because the terms concat and the open
and close parentheses are not in italics,
you must include them exactly as shown in your JavaScript code.

Arguments

If a reference page documents a function, a method, or a class with a
constructor method, the "Constructor" or
"Synopsis" section is followed by an
"Arguments" subsection that describes the arguments to
the method, function, or constructor. If there are no arguments, this
subsection is simply omitted.

arg1

The arguments are described in a list here. This is the description
for argument arg1, for example.

arg2

And this is the description for argument
arg2.

Returns

If a constructor, function, or method has a return value, this
subsection explains that value.

Throws

If a constructor, function, or method can throw an exception, this
subsection lists the types of exceptions that may be thrown and
explains the circumstances under which this can occur.

Properties

If the reference page documents a class, the "Properties"
section lists the properties defined by the class and provides short
explanations of each. In this core reference section, each property
also has a complete reference page of its own. For example, the
reference page for the Array class lists the
length property in this section and gives a brief
explanation of it, but the property is fully documented in the
"Array.length" reference page. The property listing looks
like this:

prop1

This is a summary of property prop1, including its
type, its purpose or meaning, and whether it is read-only or
read/write.

prop2

This is the same for prop2.

Methods

The reference page for a class that defines methods includes a
"Methods" section. It is just like the
"Properties" section, except that it summarizes methods
instead of properties. All methods also have reference pages of their
own.

Description

Most reference pages contain a "Description" section,
which is the basic description of the class, method, function, or
property that is being documented. This is the heart of the reference
page. If you are learning about a class, method, or property for the
first time, you may want to skip directly to this section and then go
back and look at previous sections such as "Arguments,"
"Properties," and "Methods." If you are
already familiar with a class, method, or property, you probably
won''''t need to read this section and instead will just want to
quickly look up some specific bit of information (for example, from
the "Arguments" or "Properties" sections).

In some entries, this section is no more than a short paragraph. In
others, it may occupy a page or more. For some simple methods, the
"Arguments" and "Returns" sections document
the method sufficiently by themselves, so the
"Description" section is omitted.

Example

Some pages include an example that shows typical usage. Most pages do
not contain examples, however -- you''''ll find those in first
half of this book.

Bugs

When an item doesn''''t work quite right, this section describes
the bugs. Note, however, that this book does not attempt to catalog
every bug in every version and implementation of JavaScript.