Steve1999

Below, you¡¯ll see a complete example of Xml documentation of a method. One at our company has suggested that we do this for **all** methods, private or public, properties private or public, etc..everything. As much as I think xml docs are great, esp. on public, this seems like overkill to me. I feel that we¡¯ll spend most of our time writing XML documentation for small methods (mostly private), and that this will encourage devs to not properly factor code into smaller chunks. Do you agree or disagree Where do you suggest drawing the line

//<summary>
/// Save a <see cref="Foo.Bar.Client.Document"/> to the repository with a new name.
///</summary>
///<remarks>
/// The content location is an alternative way of getting bytes into the Vault database.
/// This location must a valid, absolute file location on the server (e.g.,
/// d:\docs\foo.bar). If this property is set then the bytes represented by the
/// Contents property will not be passed when the document is added, checked in or saved
/// to the rRepository. In this scenario another mechanism for getting the bytes to
/// the server must be used.
///</remarks>
///<param name="document">
/// The <see cref=" Foo.Bar.Client.Document "/> to save.
///</param>
///<param name="newName">The new filename for the document.</param>
///<param name="contentLocation">
/// An alternative location for the <i>document content</i>. The responsibility for
/// getting the content to a location that the Vault server can retrieved it from is the
/// responsibility of an external entity.
///</param>
///<exception cref="Foo.Bar.Client.UserNotAuthenticatedException">
/// Thrown if the user has not been authenticated.
///</exception>
///<exception cref="System.ArgumentNullException">
/// Thrown if either <i>document</i> is <b>null</b> or <i>newName</i> <b>null</b> or
/// <b>empty</b>. Also thrown if the repository requires comments and <i>comments</i> is /// <b>null</b> or <b>empty</b>.
///</exception>
///<exception cref="Foo.Bar.Client.DocumentException">
/// Thrown under the following conditions:
/// <list type="bullet">
/// <item>If the repository has auto-naming turned off and the document's <see /// cref="Document.Name"/> is <b>null</b> or <b>empty</b>.
/// </item>
/// <item>The document's <see cref="Document.FileType"/> is <b>null</b> or
/// <b>empty</b>.
/// </item>
/// <item>The document's <see cref="Document.ParentFolder"/> is ///
/// <b>null</b>.
/// </item>
/// <item>The document's <see cref=".Vault.Client.Document.Contents"/> is
/// <b>null</b> or the <see cref=".Vault.Client.Document.Contents"/> length /// equals zero and <i>contentLocation</i> is <b>null</b> or <b>empty</b>.
/// </item>
/// </list>
///</exception>
///<exception cref="Foo.Bar.Client.FolderCannotAcceptDocumentsException">
/// Thrown when the document's <see cref="Document.ParentFolder"/> cannot accept
/// documents.
///</exception>
///<exception cref="Foo.Bar.Client.UnableToSaveDocumentException">
/// Thrown if the <i>document</i> cannot be saved to Vault.
///</exception>
public virtual void SaveDocumentAs(Document document,
string newName,
string contentLocation)
{
// Method implementation
}



Re: Visual C# General Xml documentation: how much is ideal?

theblueeyz

Personally - that level of documentation on public methods is probably a welcome addition. The one complaint you always hear is lack of documentation. This level of documentation may even be warranted for protected methods...

For the private ones though, the only person who will ever see the private methods are people maintaining the code. As far as that goes, I would think that maintainer would only need to know what the original developer *intended* the function to do - everything else is filler, in terms of who's writing it. In that sense, the XML documentation is ill-suited to the job: the maintainer is going to need comments scattered through the method to explain potentially confusing sections, and a summary of what the method should do.

I can't see there being a point in bringing that level of documentation to bear on private methods. Personally, I don't create that much documentation for the private methods, only enough to help future maintainers. I do spend alot of time on the public and protected stuff though.

My two cents.