Csharp Distributed Class Method And Documentation Test -- Per Erik Strandberg

Abstract

I wanted to test the partial keyword in C# and apply it on a class and a method (you can also apply it on an interface or struct). I implement a class in four files and a test program in a fifth.

The really interesting part is that partial methods are implied to be private and that you may declare them once and implement them once. Classes can be spread out more. The documentation seems to be treated a bit fuzzy.

According to MSDN (see links below) partial classes can be nice: When working on large projects, spreading a class over separate files enables multiple programmers to work on it at the same time. [...] When working with automatically generated source, code can be added to the class without having to recreate the source file. [...] As I see it the key point here is automatically generated - otherwise I'd never use it I think. But it is still interesting.

Download my little test project here: [1]

The test program

I want to test a writing the point class i many files - and this is the test program. It implies that there is a point class with a method Dist() and a contructor.

using System;
using System.Collections.Generic;
using System.Text;

namespace DistributedDocumentationTest
{
    class PointTest
    {
        static void Main(string[] args)
        {
            Point p = new Point(2, 3, 4);

            Console.WriteLine("Distance: {0}", p.Dist());
            Console.WriteLine("Press any key to continue. . . ");
            Console.ReadKey(true);
        }
    }
}

The point class

The point class contains:

three private integers x, y and z
constructor
a public Dist method that returns a float
a partial (and thus private) Distance with a reference double.

But to make things a bit messy I implement it in four files.

Part one

Here I declare the integer x, the Distance method and implement the constructor. I also add a summary to the Distance method.

using System;
using System.Collections.Generic;
using System.Text;

namespace DistributedDocumentationTest
{
    public partial class Point
    {
        private int x;

        /// <summary>
        /// Compute distance from origo.
        /// </summary>
        partial void Distance(ref double dist);

        /// <summary>
        /// Constructor sets coordinates..
        /// </summary>
        /// <param name="x">Distance from origo in x-dimension</param>
        /// <param name="y">Distance from origo in y-dimension</param>
        /// <param name="z">Distance from origo in z-dimension</param>
        public Point(int x, int y, int z)
        {
            this.x = x;
            this.y = y;
            this.z = z;
        }
    }
}

Part two

Here I add two summaries to the class, add the integer y, and the Dist method.

using System;
using System.Collections.Generic;
using System.Text;

namespace DistributedDocumentationTest
{
    /// <summary>
    /// A class for managing points.
    /// </summary>
    /// <summary>
    /// This class is very special - I like it a lot.
    /// </summary>
    public partial class Point
    {
        private int y;

        /// <summary>
        /// Get distance from origo.
        /// </summary>
        /// <returns>Distance in some kind of units from origo.</returns>
        public double Dist()
        {
            double dist = double.NaN;
            this.Distance(ref dist);
            return dist;

        }
    }
}

Part three

The third part contains another summary of the class and the z integer.

using System;
using System.Collections.Generic;
using System.Text;

namespace DistributedDocumentationTest
{
    /// <summary>
    /// Pointhandling class.
    /// </summary>
    public partial class Point
    {
        private int z;
    }
}

Part four

Here we implement the partial Distance method and document the parameter (the method got a summary near the declaration).

using System;
using System.Collections.Generic;
using System.Text;

namespace DistributedDocumentationTest
{
    public partial class Point
    {
        /// <param name="dist">Some kind of distance</param>
        partial void Distance(ref double dist)
        {
            dist = Math.Pow(Math.Pow(this.x, 2) + Math.Pow(this.y, 2) + Math.Pow(this.z, 2), 0.5);
        }
    }
}

The documentation

The documentaion generated by the compiler contains multiple summaries for the Point class and only the documentation written near the implementation of the Distance method - not the documentation written near the declaration.

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>DistributedDocumentationTest</name>
    </assembly>
    <members>
        <member name="T:DistributedDocumentationTest.Point">
            <summary>
            A class for managing points.
            </summary>
            <summary>
            This class is very special - I like it a lot.
            </summary>
            <summary>
            Pointhandling class.
            </summary>
        </member>
        <member name="M:DistributedDocumentationTest.Point.#ctor(System.Int32,System.Int32,System.Int32)">
            <summary>
            Constructor sets coordinates..
            </summary>
            <param name="x">Distance from origo in x-dimension</param>
            <param name="y">Distance from origo in y-dimension</param>
            <param name="z">Distance from origo in z-dimension</param>
        </member>
        <member name="M:DistributedDocumentationTest.Point.Dist">
            <summary>
            Get distance from origo.
            </summary>
            <returns>Distance in some kind of units from origo.</returns>
        </member>
        <member name="M:DistributedDocumentationTest.Point.Distance(System.Double@)">
            <param name="dist">Some kind of distance</param>
        </member>
    </members>
</doc>

Partial Classes and Methods (C# Programming Guide) [2]
Partial Class Definitions (C# Programming Guide) [3]
Another excellent tutorial on partial classes and methods is available here: [4]

This page belongs in Kategori Programmering

Csharp Distributed Class Method And Documentation Test