Archives

Archives / 2008 / August

  • GhostDoc Tweaks

    No Comments

    When moving to a new development machine recently, I noticed that I was using a couple of (minor) customizations to GhostDoc on the old machine that are not included in the default configuration. Most of them were rather specific, but three custom rules that may be of general interest are for overrides of the methods ToString(), Equals() and GetHashCode(). Without the rules, the documentation is inherited from System.Object:

    /// <summary>
/// Returns a <see cref="T:System.String"/> that represents the current <see cref="T:System.Object"/>.
/// </summary>
/// <returns>
/// A <see cref="T:System.String"/> that represents the current <see cref="T:System.Object"/>.
/// </returns>
public override string ToString()

/// <summary>
/// Determines whether the specified <see cref="T:System.Object"/> is equal to the current <see cref="T:System.Object"/>.
/// </summary>
/// <param name="obj">The <see cref="T:System.Object"/> to compare with the current <see cref="T:System.Object"/>.</param>
/// <returns>
/// true if the specified <see cref="T:System.Object"/> is equal to the current <see cref="T:System.Object"/>; otherwise, false.
/// </returns>
/// <exception cref="T:System.NullReferenceException">The <paramref name="obj"/> parameter is null.</exception>
public override bool Equals( object obj )

/// <summary>
/// Serves as a hash function for a particular type.
/// </summary>
/// <returns>
/// A hash code for the current <see cref="T:System.Object"/>.
/// </returns>
public override int GetHashCode() 

    The comments are OK at first sight, but I don't really like the references to System.Object, I prefer "the current instance" instead. Fortunately, changing this in GhostDoc is pretty easy.

    In general, to replace the generated documentation for a specific method, property, etc., simply define a custom rule and make sure has a higher priority than the rule that would create the documentation otherwise (in the case of the above methods that would be the "inherited documentation" rule).

    The new rules are available as a configuration file you can download here (see the included ReadMe for instructions how to use it).

    Importing this file will not affect other parts of your configuration, but creating a backup of your current configuration is never a bad idea. After the import the rules will automatically have the highest priority, so no other steps are necessary.