Orchestra Technology

1 Objetivo

O propósito deste artigo é apresentar os procedimentos para gerar uma documentação de código a partir dos comentários XML.

2 Requerimentos de sistema

A solução proposta foi desenvolvida utilizando-se os softwares abaixo:
• Windows Server 2003 R2 Enterprise Edition SP2.
• .NET Framework 2.0.
• Visual Studio 2005 Team Suite.
• HTML Help WorkShop
• SandCastle 2.3.8000.26.
• SandCastle Help File Builder 1.6.0.2.

3 Acrônimos

Acrônimo	Descrição
VO	Value Object
CHM	Compiled HTML Help

4 Procedimentos

4.1 Configuração do Visual Studio.NET

A primeira etapa do procedimento é configurar os seus projetos no VS.NET para gerarem o arquivo XML de documentação quando mesmo for compilado. Para obter este resultado, siga para as propriedades do projeto e selecione a opção XML documentation file na seção Build, como mostra a ilustração abaixo:

4.2 Comentando o seu código

A utilização de comentários no código é muito importante, talvez não para você mesmo naquele momento da confecção do código, mas quando tiver de realizar alguma manutenção corretiva ou preventiva depois de alguns meses ou quando outra pessoa suportará seu código. Portanto, não confie na sua boa memória, comente seu código. Abaixo segue um exemplo de uma classe (VO) comentada:

using System;

namespace OrchestraTechnology.SandCastle.VO.Security
{
    /// <summary>
    /// Classe para transferência dos dados de um usuário.
    /// </summary>
    [System.Serializable]
    public class User
    {
        #region Attributes
        private string firstName;
        private string lastName;
        private string email;
        #endregion

        #region Properties
        /// <summary>
        /// Nome do usuário
        /// </summary>
        public string FirstName
        {
            get { return firstName; }
            set { firstName = value; }
        }

        /// <summary>
        /// Sobrenome do usuário
        /// </summary>
        public string LastName
        {
            get { return lastName; }
            set { lastName = value; }
        }

        /// <summary>
        /// Endereço de e-mail do usuário
        /// </summary>
        public string Email
        {
            get { return email; }
            set { email = value; }
        }
        #endregion

        #region Constructors
        /// <summary>
        /// Construtor padrão.
        /// </summary>
        /// <example>
        /// <code>
        /// OrchestraTechnology.SandCastle.VO.Security.User user = new OrchestraTechnology.SandCastle.VO.Security.User();
        /// </code>
        /// </example>
        public User()
        {
        }

        /// <summary>
        /// Construtor alternativo.
        /// </summary>
        /// <param name="firtName">Nome do usuário</param>
        /// <param name="lastName">Sobrenome do usuário</param>
        /// <param name="email">Endereço de e-mail do usuário</param>
        /// <example>
        /// <code>
        /// OrchestraTechnology.SandCastle.VO.Security.User user = new OrchestraTechnology.SandCastle.VO.Security.User("Evandro", "Paula", "evandro@orchestratechnology.com.br");
        /// </code>
        /// </example>
        public User(string firtName, string lastName, string email)
        {
            this.FirstName = firstName;
            this.LastName = lastName;
            this.Email = email;
        }
        #endregion
    }
}

4.3 Inspecionando o arquivo XML gerado

Quando compilar o projeto uma arquivo XML será gerado de acordo com as configurações (diretório e nome do arquivo) realizadas no passo 5.2.

<xml version="1.0"?>
<xml version="1.0"?>
<doc>
    <assembly>
        <name>OrchestraTechnology.SandCastle.VO</name>
    </assembly>
    <members>
        <member name="T:OrchestraTechnology.SandCastle.VO.Security.User">
            <summary>
            Classe para transferência dos dados de um usuário.
            </summary>
        </member>
        <member name="M:OrchestraTechnology.SandCastle.VO.Security.User.#ctor">
            <summary>
            Construtor padrão.
            </summary>
            <example>
            <code>
            OrchestraTechnology.SandCastle.VO.Security.User user = new OrchestraTechnology.SandCastle.VO.Security.User();
            </code>
            </example>
        </member>
        <member name="M:OrchestraTechnology.SandCastle.VO.Security.User.#ctor(System.String,System.String,System.String)">
            <summary>
            Construtor alternativo.
            </summary>
            <param name="firtName">Nome do usuário</param>
            <param name="lastName">Sobrenome do usuário</param>
            <param name="email">Endereço de e-mail do usuário</param>
            <example>
            <code>
            OrchestraTechnology.SandCastle.VO.Security.User user = new OrchestraTechnology.SandCastle.VO.Security.User("Evandro", "Paula", "evandro@orchestratechnology.com.br");
            </code>
            </example>
        </member>
        <member name="P:OrchestraTechnology.SandCastle.VO.Security.User.FirstName">
            <summary>
            Nome do usuário
            </summary>
        </member>
        <member name="P:OrchestraTechnology.SandCastle.VO.Security.User.LastName">
            <summary>
            Sobrenome do usuário
            </summary>
        </member>
        <member name="P:OrchestraTechnology.SandCastle.VO.Security.User.Email">
            <summary>
            Endereço de e-mail do usuário
            </summary>
        </member>
    </members>
</doc>

Note que nós são criados para manter as referências do assembly e seus membros, bem como como os comentários que foram inseridos.

4.4 SandCastle Help File Builder

A etapa final compreende na criação de um projeto no SandCastle Help File Builder referenciando os arquivos XML que são gerados durante a compilação e realizar o Build do projeto.