1.6 Documentation Conventions

Rogue Wave uses special conventions for path name variables, type, and the naming of classes and functions. These conventions are described here. The first time you use a Rogue Wave product, you may want to read this section thoroughly.

1.6.1 Path Name Variables

Rogue Wave documentation uses variables as placeholders in path names to indicate information that changes according to your product, compiler, platform, and installation. These variables are set off by an italic font, as in x.

Rogue Wave provides the Software Parts Manager (SPM) application to help you install and build Rogue Wave products. SPM installations use a number of variables that allow you to manage multiple builds. Table 3 explains the path name variables used in SPM installations.

Table 3 -- Path name variables (SPM installations)

Convention	Definition	Example
`rw_root`	The name you gave your Rogue Wave root directory.	`c:\rwav`
`ver`	The version number of your product, operating system, or compiler.	`thr0200 WINNT4 MSVC60`
`osfam`	A mnemonic representing your operating system family: `w` for Windows, and `u` for Unix. Also represented as `[w\|u]`.	`thr0200w`
`OS`	A mnemonic representing your operating system.	`WIN95 SOLARIS`
`COMPILER`	A mnemonic representing your compiler.	`MSVC`
`buildtype`	A build type, consisting of a build number, binding type, and optional user-defined library suffix.	`7s` `7d_test`
`ext`	An extension.	`.lib`
`\`	A delimiter in a path name. Unix users should replace `\` with `/`.	`parts\htmldocs`

The following example shows how these SPM variables can be used.

rw_root\parts\thrver+osfam\source\obj\OS+ver\COMPILER+ver\buildtype

The variable-filled path above could become the specific path below.

c:\rwav\parts\thr0200w\source\obj\WINNT4\MSVC60\7s

This specific path indicates a c:\rwav root directory containing the product Threads.h++ 2.0. The product is configured for Windows NT, the Microsoft Visual C++ compiler, and the 7s library build type. Build types are explained in detail in the Build Guide.

1.6.2 Type Conventions

Rogue Wave documentation uses type conventions to indicate special meanings. These conventions are listed in Table 4.

Table 4 -- Type conventions

Convention	Purpose	Example
`courier`	Code, variables, symbols, operating system commands, and the names of functions, macros, directories, and files.	`fin.close();` the `rw_root` directory
`x`	A variable in a file name or directory path. Table 3 lists possible variables.	`ver` is the version number of your product
italic	Emphasis. New terms.	operating system family the object state is...
bold	Emphasis. Commands from an interface. Rogue Wave product names.	Deprecated class. Use... the OK button Threads.h++ files
*bold italic*	Class names.	*RWCString*
`.` `.` `.` or `...`	Code is missing.	`main()` `{ .` `. //Something` `. //happens!` `}`

1.6.3 Naming Conventions

Most Rogue Wave class names and types start with the capital letters RW. In Threads.h++, templatized classes start with RWT. Template parameter values appear in angle brackets < > like this: RWTMonitor<Mutex>. Formal template parameters appear in text only when they are important to the discussion, so you may occasionally see this: RWTMonitor<Mutex>, but generally it is simply RWTMonitor.

All member function names start with a lower case letter, but subsequent words are capitalized. All global function names start with the lower case letters rw. In most class and function names, words are fully spelled out, not abbreviated. Here are some examples:

*RWThread*	A class name
`requestInterrupt()`	A function name
`rwServiceCancellation()`	A global function name

In our manuals, we sometimes refer to an instance of a class by an English name; for example, the "runnable" instead of "the RWRunnable instance." We do this for readability when the meaning should be clear from context. If there is possible ambiguity, however, we use the actual class name.

Throughout the documentation, references to "self" mean *this.