Changeset 4000


Ignore:
Timestamp:
Nov 26, 2007, 1:03:36 PM (16 years ago)
Author:
Martin Svensson
Message:

References #553 Write "Javadoc" section.

Location:
trunk/doc/src/docbook/developerdoc
Files:
1 deleted
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/developerdoc/documentation.xml

    r3946 r4000  
    17851785  </sect1>
    17861786 
     1787  <sect1 id="documentation.javadoc">
     1788    <title>Javadoc</title>
     1789
     1790    <para>
     1791      Existing Javadoc documentation is available online at:
     1792      <ulink url="http://base.thep.lu.se/chrome/site/doc/api/index.html"
     1793        >http://base.thep.lu.se/chrome/site/doc/api/index.html</ulink>.
     1794    </para>
     1795   
     1796    <para>
     1797      The BASE API is devided into four different parts in Javadoc; Public, Mixed public and
     1798      internal, Internal and Extension. Introduction to the Base API and it's parts can be
     1799      found on the start page of Base Javadoc. Plugin developers and other external developers
     1800      should pay most attention to the public API. What we consider to be the public part of the API is discussed in
     1801      <xref linkend="api_overview.public_api" />.
     1802    </para>
     1803
     1804    <sect2 id="javadoc.writing">
     1805      <title>Writing javadoc</title>
     1806      <para>
     1807        This section only covers Javadoc comments, how to write proper none-Javadoc comments
     1808        are described in
     1809        <xref linkend="core_ref.rules.style" />
     1810      </para>
     1811      <para>
     1812        General information about Javadoc and how it is written in a proper way can be found
     1813        at
     1814        <ulink url="http://java.sun.com/j2se/javadoc/writingdoccomments/index.html">
     1815          http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
     1816        </ulink>
     1817        . The rule when coding in Base is that all packages, classes, interfaces, public
     1818        methods and public attributes must be commented in Javadoc style. It is also
     1819        recommended that private and protected methods has some comments, but maybe not as
     1820        detailed as the public ones. Below follow more specific details what to have in mind
     1821        when writing Javadoc in the Base project.
     1822      </para>
     1823      <variablelist>
     1824        <varlistentry>
     1825          <term>General</term>
     1826          <listitem>
     1827            <para>
     1828              General things that are common for all Javadocs comments in Base.
     1829            </para>
     1830            <itemizedlist>
     1831              <listitem>
     1832                <para>All comments should be in English.</para>
     1833              </listitem>
     1834              <listitem>
     1835                <para>Do not start each new line of comment with a star.</para>
     1836              </listitem>
     1837              <listitem>
     1838                <para>
     1839                  If a comment only should be shown in the internal documentation
     1840                  and not in the public, it should be tagged with
     1841                  <synopsis>@base.internal</synopsis>
     1842                </para>
     1843              </listitem>
     1844            </itemizedlist>
     1845          </listitem>
     1846        </varlistentry>
     1847       
     1848        <varlistentry>
     1849          <term>Package comments</term>
     1850          <listitem>
     1851            <para>
     1852              Package comments should be placed in a file named package.html in the source code
     1853              directory.
     1854            </para>
     1855          </listitem>
     1856        </varlistentry>
     1857       
     1858        <varlistentry>
     1859          <term>Class and interface comments</term>
     1860          <listitem>
     1861            <para>
     1862              A comment for a class or interface should start with a general
     1863              description. The class comment should then give information about what
     1864              the class can be used for, while an interface comment more should inform
     1865              which kinds of classes that are supposed to implement the interface.
     1866            </para>
     1867            <variablelist>
     1868              <varlistentry>
     1869                <term><synopsis>@author</synopsis></term>
     1870                <listitem>
     1871                  <para>The first name of the author(s) of the class.</para>
     1872                </listitem>
     1873              </varlistentry>
     1874              <varlistentry>
     1875                <term><synopsis>@version</synopsis></term>
     1876                <listitem>
     1877                  <para>From which version of Base the class is available.</para>
     1878                </listitem>
     1879              </varlistentry>
     1880              <varlistentry>
     1881                <term><synopsis>@see</synopsis></term>
     1882                <listitem>
     1883                  <para>Optional. Links to some related subjects.</para>
     1884                </listitem>
     1885              </varlistentry>
     1886              <varlistentry>
     1887                <term><synopsis>@base.modified</synopsis></term>
     1888                <listitem>
     1889                  <para>
     1890                    Optional. Some classes has this tag too. This is for give the
     1891                    class-file a time stamp when it is checked in to subversion.
     1892                  </para>
     1893                </listitem>
     1894              </varlistentry>
     1895            </variablelist>
     1896          </listitem>
     1897        </varlistentry>
     1898       
     1899        <varlistentry>
     1900          <term>Method comments</term>
     1901          <listitem>
     1902            <para>
     1903              A method comment should start with a general description of the method
     1904              and what it does. The following tags must be present in this order:
     1905            </para>
     1906            <variablelist>
     1907              <varlistentry>
     1908                <term>
     1909                  <synopsis>@param</synopsis></term>
     1910                <listitem>
     1911                  <para>
     1912                    One tag for each parameter of the method. Make sure to tell
     1913                    what values are allowed and what will happen if a disallowed
     1914                    value is passed.
     1915                  </para>
     1916                </listitem>
     1917              </varlistentry>
     1918              <varlistentry>
     1919                <term><synopsis>@return</synopsis></term>
     1920                <listitem>
     1921                  <para>
     1922                    What is returned by the method. Make sure to tell what
     1923                    values can be returned (ie. if it can be null).
     1924                  </para>
     1925                </listitem>
     1926              </varlistentry>
     1927              <varlistentry>
     1928                <term><synopsis>@throws</synopsis></term>
     1929                <listitem>
     1930                  <para>
     1931                    One tag for each exception that the method can throw and
     1932                    describe when and why it will be thrown.
     1933                  </para>
     1934                </listitem>
     1935              </varlistentry>
     1936              <varlistentry>
     1937                <term>
     1938                  <synopsis>@since</synopsis>
     1939                </term>
     1940                <listitem>
     1941                  <para>
     1942                    Use only this tag together with methods added in a later
     1943                    version then the one the class was created in. It holds which
     1944                    version the method first was available in.
     1945                  </para>
     1946                </listitem>
     1947              </varlistentry>                           
     1948              <varlistentry>
     1949                <term>
     1950                  <synopsis>@see</synopsis></term>
     1951                <listitem>
     1952                  <para>
     1953                    Optional. Link to relevant information, one tag for each
     1954                    link.
     1955                  </para>
     1956                </listitem>
     1957              </varlistentry>
     1958            </variablelist>
     1959          </listitem>
     1960        </varlistentry>
     1961       
     1962        <varlistentry>
     1963          <term>Attribute comments</term>
     1964          <listitem>
     1965            <para>
     1966              If the attribute is a static final, describe what the attribute is for
     1967              an where it is typically used. Other attributes can often be explained
     1968              through their getter and setter methods.
     1969            </para>
     1970          </listitem>
     1971        </varlistentry>
     1972      </variablelist>
     1973    </sect2>
     1974  </sect1>
    17871975</chapter>

  • trunk/doc/src/docbook/developerdoc/index.xml

    r3884 r4000  
    3333  <include file="webservices.xml"/>
    3434  <include file="api_overview.xml"/>
    35   <include file="javadoc.xml"/>
    3635  <include file="documentation.xml"/>
    3736  <include file="core_ref.xml"/>
Note: See TracChangeset for help on using the changeset viewer.