Standardy dokumentowania kodu

Do tworzenia dokumentacji w C# i C++ używamy narzędzia doxygen. Poniżej opis standardowej składni^[1]. Dla Javascriptu wykorzystujemy narzędzie JSDoc.

Co i jak dokumentujemy

Aktualnie pracujemy na dość dużych repozytoriach, z dużą ilością już napisanych linii kodu, nie ma więc praktycznej możliwości udokumentowania wszystkiego. W ramach realizacji tematu staramy się opisywać co najmniej klasy oraz metody i składowe publiczne które edytujemy, bądź dodajemy, a także szczególnie ważne miejsca w kodzie. W ramach review, mamy obowiązek sprawdzić, czy temat jest dobrze udokumentowany.

Języki programowania

C++

Są 3 typy komentarzy

• skrócone, czyli jednolinijkowe //!
• szczegółowe, czyli w wielu liniach /*! .. */
• opisy metod, czyli sklejone wszystkie komentarze które są między { a } w ciele metod.

Przykład

//!  A test class. 
/*!
  A more elaborate class description.
*/
class QTstyle_Test
{
  public:
    //! An enum.
    /*! More detailed enum description. */
    enum TEnum { 
                 TVal1, /*!< Enum value TVal1. */  
                 TVal2, /*!< Enum value TVal2. */  
                 TVal3  /*!< Enum value TVal3. */  
               } 
         //! Enum pointer.
         /*! Details. */
         *enumPtr, 
         //! Enum variable.
         /*! Details. */
         enumVar;  

    //! A constructor.
    /*!
      A more elaborate description of the constructor.
    */
    QTstyle_Test();
    //! A destructor.
    /*!
      A more elaborate description of the destructor.
    */
   ~QTstyle_Test();

    //! A normal member taking two arguments and returning an integer value.
    /*!
      \param a an integer argument.
      \param s a constant character pointer.
      \return The test results
      \sa QTstyle_Test(), ~QTstyle_Test(), testMeToo() and publicVar()
    */
    int testMe(int a,const char *s);

    //! A pure virtual member.
    /*!
      \sa testMe()
      \param c1 the first argument.
      \param c2 the second argument.
    */
    virtual void testMeToo(char c1,char c2) = 0;

    //! A public variable.
    /*!
      Details.
    */
    int publicVar;

    //! A function variable.
    /*!
      Details.
    */
    int (*handler)(int a,int b);
};

Co jest renderowane w następujący sposób.

Szczegóły Dokumentacji doxygen

C#

Używamy standardowej w c# składni, która jest wspierana przez Visual Studio

/// <summary>
/// Class level summary documentation goes here.</summary>
/// <remarks>
/// Longer comments can be associated with a type or member through
/// the remarks tag.</remarks>
public class TestClass : TestInterface
{
    /// <summary>
    /// Store for the name property.</summary>
    private string _name = null;

    /// <summary>
    /// The class constructor. </summary>
    public TestClass()
    {
        // TODO: Add Constructor Logic here.
    }

    /// <summary>
    /// Name property. </summary>
    /// <value>
    /// A value tag is used to describe the property value.</value>
    public string Name
    {
        get
        {
            if (_name == null)
            {
                throw new System.Exception("Name is null");
            }
            return _name;
        }
    }

    /// <summary>
    /// Description for SomeMethod.</summary>
    /// <param name="s"> Parameter description for s goes here.</param>
    /// <seealso cref="System.String">
    /// You can use the cref attribute on any tag to reference a type or member 
    /// and the compiler will check that the reference exists. </seealso>
    public void SomeMethod(string s)
    {
    }

    /// <summary>
    /// Some other method. </summary>
    /// <returns>
    /// Return results are described through the returns tag.</returns>
    /// <seealso cref="SomeMethod(string)">
    /// Notice the use of the cref attribute to reference a specific method. </seealso>
    public int SomeOtherMethod()
    {
        return 0;
    }

    public int InterfaceMethod(int n)
    {
        return n * n;
    }

    /// <summary>
    /// The entry point for the application.
    /// </summary>
    /// <param name="args"> A list of command line arguments.</param>
    static int Main(System.String[] args)
    {
        // TODO: Add code to start application here.
        return 0;
    }
}

/// <summary>
/// Documentation that describes the interface goes here.
/// </summary>
/// <remarks>
/// Details about the interface go here.
/// </remarks>
interface TestInterface
{
    /// <summary>
    /// Documentation that describes the method goes here.
    /// </summary>
    /// <param name="n">
    /// Parameter n requires an integer argument.
    /// </param>
    /// <returns>
    /// The method returns an integer.
    /// </returns>
    int InterfaceMethod(int n);
}

Javascript

Używamy narzędzia JSDoc, które jest ogólnie przyjętym standardem tworzenia dokumentacji w kodzie js.

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

Dodatkowa dokumentacja w plikach md

Dodatkowo w obydwu narzędziach dopuszczalne jest tworzenie dodatkowych stron z dokumentacją, które są dołączane do dokumentacji generowanej z kodu. Są to pliki z rozszerzeniem .md. Plik README.md jest traktowany jako strona startowa dla dokumentacji. Pozostałe pliki są w folderze /doc. Składnia plików markdown jest bardzo prosta i opisana np. na githubie.

[1]: Doxygen wspiera też wiele swoich specjalnych poleceń