Synopsis
The most important part of every quick-reference entry is the synopsis, which follows the title and description. The synopsis for a type looks a lot 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 supertype 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 those 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 are not to be used literally. The member listings are printed on alternating gray and white backgrounds to keep them visually separate.
Member availability and flags
Each member listing is a single line that defines the API for that member. These listings use C# syntax, so their meaning is immediately clear to any C# programmer. There is some auxiliary information associated with each member synopsis, however, that requires explanation.
The area to the right of the member synopsis is used to display a variety of flags that provide additional information about the member. Some of these flags indicate additional specification details that do not appear in the member API itself.
The following flags may be displayed to the right of a member synopsis:
- Overrides
Indicates that a method overrides a method in one of its supertypes. The flag is followed by the name of the supertype that the method overrides.
- Implements
Indicates that a method implements a method in an interface. The flag is followed by the name of the interface that is implemented.
- =
For enumeration fields and constant fields, this flag is followed by the constant value of the field. Only constants of primitive and
Stringtypes and constants with the valuenullare displayed. Some constant values are specification details, while others are implementation details. Some constants are platform dependent, such asSystem.BitConverter.IsLittleEndian. Platform-dependent values shown in this book conform to theSystem.PlatformID.Win32NTplatform (32-bit Windows NT, 2000, or XP). The reason that symbolic constants are defined, however, is so you can write code that does not rely directly upon the constant value. Use this flag to help you understand the type, but do not rely upon the constant values in your own programs.
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 static (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 each other in a type synopsis with C# comments, such as // Public Constructors, // Protected Instance Properties, and // Events. The various functional categories are as follows (in the order in which they appear in a type synopsis):
- Constructors
Displays the constructors for the type. Public constructors and protected constructors are displayed separately in subgroupings. If a type defines no constructor at all, the C# compiler adds a default no-argument constructor that is displayed here. If a type defines only private constructors, it cannot be instantiated, so no constructor appears. Constructors are listed first because the first thing you do with most types is instantiate them by calling a constructor.
- Fields
Displays all of the fields defined by the type, including constants. Public and protected fields are displayed in separate subgroups. Fields are listed here, near the top of the synopsis, because constant values are often used throughout the type as legal values for method parameters and return values.
- Properties
Lists all the properties of the type, breaking them down into subgroups for public and protected static properties and public and protected instance properties. After the property name, its accessors (get or set) are shown.
- Static Methods
Lists the static methods (class methods) of the type, broken down into subgroups for public static methods and protected static methods.
- Public Instance Methods
Contains all of the public instance methods.
- Protected Instance Methods