Documentando seu Código Fonte em C# (Csharp) no Visual Studio 2008

Este post terá a finalidade de mostrar como documentar funções, métodos, atributos de uma classe em nosso dia-a-dia de desenvolvimento de software, utilizando os recursos do Visual Studio 2008. Quando desejar documentar seus tipos C# no Visual Studio 2008, seu primeiro passo é utilizar a nova notação de comentário de código com três barras “///”. Uma vez que um comentário da documentação tenha sido declarado, você tem liberdade para utilizar quaisquer elementos XML bem formados, inclusive o conjunto recomendado mostrado a baixo:

Elementos Pre-Definidos de Documento XML  e suas descrições

<c> – Indica que o texto a seguir deve ser uma “fonte de código” especificada.
<code> -Indica que varias linhas devem ser marcadas como código.
<exemple> – Cria um exemplo de código para o item que esta sendo descrito.
<exception> – Documenta quais exceções uma determinada classe pode gerar.
<list> – Insere uma lista ou tabela ao arquivo de documentação.
<param> – Descreve um determinando parâmetro.
<paramref> – Associa uma terminada Tag XML com um parâmetro especificado.
<permission> – Documenta os limites de segurança para um determinado membro.
<remarks> – Constrói uma descrição para um determinado membro.
<returns> – Documenta o valor de retorno do membro.
<see> – Faz referencia cruzada aos itens do documento.
<seealso> – Constrói uma seção “See Also” ou “Veja Também” em uma descrição.
<summary> – Documenta o “Resumo Executivo” para um determinado membro.
<values> – Documenta uma determinada propriedade.

Exemplo sem passagem de parâmetro e sem retorno

/// <summary>
/// Abre a Conexao com o banco de dados ou exibe o erro caso a base esteja
/// inconsistente
/// </summary>
private static void abreConexao()
{
    try
    {
       conn.Open(); //Abre a conexão com BD
    }
    catch (Exception e)
    {
       throw new Exception("Erro ao abrir a conexão: " + e.Message);
    }
}

Exemplo com passagem de parâmetros e com retorno do membro

/// <summary>
/// Executa uma query SELECT considerando os parâmetros (SqlParameter)
/// </summary>
/// <param name="query">Query a ser executado no banco de dados</param>
/// <param name="parameters">Parâmetros da query (Ex. "@cod, @num, @nome") etc.</param>
/// <returns>Retorna o DataSet da query executada</returns>
public static DataSet seleciona(string query, params SqlParameter[] parameters)
{
    try
    {
        DataSet ds = new DataSet();
        abreConexao();

        SqlCommand cmd = new SqlCommand(query, conn);
        foreach (SqlParameter param in parameters)
        cmd.Parameters.Add(param);
        SqlDataAdapter da = new SqlDataAdapter(cmd);
        da.Fill(ds); //Preenche DataSet
        cmd.Parameters.Clear();
        return ds;  //Retorna o DataSet já contendo os dados
    }
    catch (Exception e)
    {
        throw new Exception("Erro ao selecionar query " + query + "\n" + e.Message);
    }
    finally
    {
        fechaConexao();
    }
}

Bom esse post foi bem simples, com a finalidade de mostrar os recursos disponíveis pelo Visual Studio 2008 para documentação de código, para quem é desenvolvedor, vale uma dica, se atente em documentar pela tabela acima mostrada neste post, fica mais organizado e profissional.

Abraços até a próxima.