The remainder of the XML documentation tags describes the .NET documentation convention. They can be extended, modified, or ignored if necessary for a specific project. Table 38-2 shows the XML elements you can use for documentation.

Using Barcode printer for Software Control to generate, create QR image in Software applications.

www.OnBarcode.com

A short description of the item A long description of the item Formats characters as code within other text Multiline section of code usually used in an <example> section An example of using a class or method The exceptions a class throws A list of items Describes a parameter to a member function A reference to a parameter in other text The permission applied to a member The return value of a function A link to a member or field in the current compilation environment A link in the see also section of the documentation Describes the value of a property

Using Barcode Control SDK for Java Control to generate, create, read, scan barcode image in Java applications.

www.OnBarcode.com

In a project that has a separate technical-writing team, it may be more convenient to keep the XML text outside the code. To support this, C# provides an include syntax for XML documentation. Instead of having all the documentation before a function, you can use the following include statement: /// <include file='Foo.csx' path='doc/member[@name="Foo.Comp"]' /> This will open the Foo.csx file and look for a <doc> tag. Inside the doc section, it will then look for a <member> tag that has the name Foo.Comp specified as an attribute. In other words, it will look for something like this: <doc> <member name="Foo.Comp"> <summary>A description of the routine</summary> <param name="obj1">the first object</param> </member> </doc>

Once the compiler has identified the matching section from the include file, it proceeds as if the XML were contained in the source file.

Garbage Collection in the .NET Runtime

Garbage collection has a bad reputation in a few areas of the software world. Some programmers think they can do a better job at memory allocation than a garbage collector (GC) can. They re correct; they can do a better job but only with a custom allocator for each program and possibly for each class. Also, custom allocators are a lot of work to write, to understand, and to maintain. In the vast majority of cases, a well-tuned garbage collector will give similar or better performance to an unmanaged heap allocator. The following sections explain a bit about how the garbage collector works, how it can be controlled, and what can t be controlled in a garbage-collected world. The information presented describes the situation for platforms such as PCs and servers that run full versions of Windows. Systems with more constrained resources, such as the Pocket PC, are likely to have simpler GC systems. Note also that there are optimizations performed for multiproc and server machines (covered later in the Server vs. Workstation Garbage Collection section).

Allocation

Heap allocation in the .NET runtime world is fast; all the system has to do is make sure the managed heap has enough room for the requested object, return a pointer to that memory, and increment the pointer to the end of the object. Garbage collectors trade simplicity at allocation time for complexity at cleanup time. Allocations are really, really fast in most cases, though if there isn t enough room, a garbage collection might be required to obtain enough room for object allocation. Of course, to make sure it has enough room, the system might have to perform a garbage collection. To improve performance, large objects (greater than 20KB) are allocated from a large object heap.

Mark and Compact

The .NET garbage collector uses a Mark and Compact algorithm. When a collection is performed, the garbage collector starts at root objects (including globals, statics, locals, and CPU registers) and finds all the objects referenced from those root objects. This collection of objects denotes the objects that are in use at the time of the collection, and therefore all other objects in the system are no longer needed. To finish the collection process, all the referenced objects are copied down in the managed heap, and the pointers to those objects are all fixed up. Then, the pointer for the next available spot is moved to the end of the referenced objects. Since the garbage collector is moving objects and object references, no other operations can be going on in the system. In other words, all useful work must stop while the GC takes place.