OTHER TOPICS in Visual C#.NET

Creating ECC200 in Visual C#.NET OTHER TOPICS

In the preceding examples, you saw the use of the summary XML tag. There are also a number of other tags that C# recognizes. Table 25-3 lists some of the most important. Table 25-3. Documentation Code XML Tags

Format the enclosing lines in a font that looks like code. Mark the enclosing lines as an example. Mark a parameter for a method or constructor and allow a description. Describe a type declaration. Describe a return value. Create a See Also entry in the output document. Describe a type or a type member. Describe a property.

Types are usually declared directly inside a namespace. You can, however, also declare types inside a class or struct declaration. Types declared inside another type declaration are called nested types. Like all type declarations, nested types are templates for an instance of the type. A nested type is declared like a member of the enclosing type. A nested type can be any type. An enclosing type can be either a class or a struct.

For example, the following code shows class MyClass, with a nested class called MyCounter. class MyClass { class MyCounter { ... } ... } // Enclosing class // Nested class

Declaring a type as a nested type often makes sense if it s only meant to be used as a helper for the enclosing type. Don t be confused by the term nested. Nested refers to the location of the declaration not the location of any instances. Although a nested type s declaration is inside the enclosing type s declaration, objects of the nested type are not necessarily enclosed in objects of the enclosing type. Objects of the nested type if any are created at all are located wherever they would have been located had they not been declared inside another type. For example, Figure 25-6 shows objects of types MyClass and MyCounter, as outlined in the preceding code. The figure additionally shows a field called Counter, in class MyClass, that is a reference to an object of the nested class, which is located elsewhere in the heap.

The following code fleshes out classes MyClass and MyCounter into a full program. MyCounter implements an integer counter that starts at 0 and can be incremented using the ++ operator. When the constructor for MyClass is called, it creates an instance of the nested class and assigns the reference to the field. Figure 25-7 illustrates the structure of the objects in the code. class MyClass { class MyCounter { private int _Count = 0; public int Count { get { return _Count; } }

public static MyCounter operator++( MyCounter current ) { current._Count++; return current; } } private MyCounter counter; public MyClass() { counter = new MyCounter(); } public int Incr() { return (counter++).Count; } public int GetValue() { return counter.Count; } } class Program { static void Main( ) { MyClass mc = new MyClass(); mc.Incr(); mc.Incr(); mc.Incr(); mc.Incr(); mc.Incr(); mc.Incr(); Console.WriteLine("Total: } } {0}", mc.GetValue()); // Field of nested class // Constructor // Increment method // Get counter value

This code produces the following output: Total: 6

In 7, you learned that classes, and types in general, can have an access level of either public or internal. Nested types, however, are different in that they have member accessibility rather than type accessibility. Therefore, the following are true: A nested type declared inside a class can have any of the five class member accessibility levels public, protected, private, internal, or protected internal. A nested type declared inside a struct can have one of the three struct member accessibility levels public, internal, or private.

In both cases, the default access level of a nested type is private, which means it cannot be seen outside the enclosing type. The relationship between the members of the enclosing class and the nested class is a little less straightforward and is illustrated in Figure 25-8. The nested type has complete access to the members of the enclosing type, regardless of their declared accessibility, including members that are private and protected. The relationship, however, is not symmetrical. Although the members of the enclosing type can always see the nested type declaration and create variables and instances of it, they do not have complete access to its members. Instead, their access is limited to the declared access of the nested class members just as if the nested type were a separate type. That is, they can access the public and internal members but cannot access the private or protected members of the nested type.