21.1 Reading a Quick-Reference Entry
Each quick-reference entry contains quite a bit of information. The sections that follow describe the structure of a quick-reference entry, explaining what information is available, where it is found, and what it means. While reading the descriptions that follow, you will find it helpful to flip through the reference section itself to find examples of the described features.
21.1.1 Type Name, Namespace, Assembly, Type Category, and Flags
Each quick-reference entry begins with a four-part title that specifies the name, namespace (followed by the assembly in parentheses), and type category of the type, and may also specify various additional flags that describe the type. The type name appears in bold at the upper-left side of the title. The namespace and assembly appear in smaller print in the lower-left side, below the type name.
The upper-right portion of the title indicates the type category of the type (class, delegate, enum, interface, or struct). The "class" category may include modifiers such as sealed or abstract.
In the lower-right corner of the title, you may find a list of flags that describe the type. The possible flags and their meanings are as follows:
The title of each quick-reference entry is followed by a short description of the most important features of the type. This description may be anywhere from a couple of sentences to several paragraphs long.
The most important part of every quick-reference entry is the synopsis, which follows the title and description. The synopsis for a type looks much like its source code, except that the member bodies are omitted and some additional annotations are added. If you know C# syntax, you know how to read the type synopsis.
The first line of the synopsis contains information about the type itself. It begins with a list of type modifiers, such as abstract and sealed. These modifiers are followed by the class, delegate, enum, interface, or struct keyword and then by the name of the type. The type name may be followed by a colon (:) and a base class or interfaces that the type implements.
The type definition line is followed by a list of the members that the type defines. This list includes only members that are explicitly declared in the type, are overridden from a base class, or are implementations of an interface member. Members that are simply inherited from a base class are not shown; you will need to look up the base class definition to find those members.
Once again, if you understand basic C# syntax, you should have no trouble making sense of these lines. The listing for each member includes the modifiers, type, and name of the member. For methods, the synopsis also includes the type and name of each method parameter. The member names are in boldface, so it is easy to scan the list of members looking for the one you want. The names of method parameters are in italics to indicate that they should not be used literally. The member listings are printed on alternating gray and white backgrounds to keep them visually separate.
220.127.116.11 Member availability and flags
Each member listing is a single line that defines the syntax for that member. These listings use C# syntax, so their meaning is immediately clear to any C# programmer. Some auxiliary information associated with each member synopsis, however, requires explanation.
The area to the right of the member synopsis displays a variety of flags that provide additional information about the member. Some flags indicate additional specification details that do not appear in the member syntax itself.
The following flags may be displayed to the right of a member synopsis:
18.104.22.168 Functional grouping of members
Within a type synopsis, the members are not listed in strict alphabetical order. Instead, they are broken down into functional groups and listed alphabetically within each group. Constructors, events, fields, methods, and properties are all listed separately. Instance methods are kept separate from shared (class) methods. Public members are listed separately from protected members. Grouping members by category breaks a type down into smaller, more comprehensible segments, making the type easier to understand. This grouping also makes it easier for you to find a desired member.
Functional groups are separated from one another in a type synopsis with comments, such as:
// Protected Instance Properties
The various functional categories follow below (in the order in which they appear in a type synopsis):
21.1.4 Class Hierarchy
For any type that has a nontrivial inheritance hierarchy, the synopsis is followed by a "Hierarchy" section. This section lists all of the base classes of the type, as well as any interfaces implemented by those base classes. It also lists any interfaces implemented by an interface. In the hierarchy listing, arrows indicate base class to derived class relationships, while the interfaces implemented by a type follow the type name in parentheses. For example, the following hierarchy indicates that System.IO.Stream implements IDisposable and extends MarshalByRefObject, which itself extends Object:
System.Object System.MarshalByRefObject System.IO.Stream(System.IDisposable)
If a type has subtypes, the "Hierarchy" section is followed by a "Subtypes" section that lists those subtypes. If an interface has implementations, the "Hierarchy" section is followed by an "Implementations" section that lists those implementations. While the "Hierarchy" section shows ancestors of the type, the "Subtypes" or "Implementations" section shows descendants.
21.1.5 Cross References
The hierarchy section of a quick-reference entry is followed by optional cross-reference sections that indicate other related types and methods that may be of interest. These sections include:
21.1.6 A Note About Type Names
Throughout the quick reference, you'll notice that types are sometimes referred to by type name alone, and at other times are referred to by type name and namespace. If namespaces were always used, the type synopses would become long and hard to read. On the other hand, if namespaces were never used, it would sometimes be difficult to know what type was being referred to. The rules for including or omitting the namespace name are complex. However, they can be summarized as follows: