[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    developer.kde.org
From:       Adriaan de Groot <groot () kde ! org>
Date:       2005-09-15 21:39:57
Message-ID: 1126820397.590942.7388.nullmailer () svn ! kde ! org
[Download RAW message or body]

SVN commit 460964 by adridg:

Remove broken parts of dox policy; add a guidelines section to hammer on bits before \
they become policy.

 M  +1 -0      documentation/library/api.content  
 A             documentation/library/guidelines.php  
 M  +14 -73    policies/documentationpolicy.php  


--- trunk/developer.kde.org/documentation/library/api.content #460963:460964
@@ -8,5 +8,6 @@
 
     documentation/library/libraryref     For Writers
 >   documentation/library/howto            dox HOWTO
+>   documentation/library/guidelines       dox Guide
 >   policies/documentationpolicy           dox Policy
 >   :www.doxygen.org/manual.html           Doxygen Manual
--- trunk/developer.kde.org/policies/documentationpolicy.php #460963:460964
@@ -4,12 +4,25 @@
   include 'header.inc';
 ?>
 
-<p>Version 1.1 (June 15th 2005)</p>
+<ul>
+<li>
+  <b>Version 1.1.1 (September 16th 2005)</b> Removed policy elements 
+  11 and 12 since they were hints or guidelines, not policy.
+  See the <a href="/documentation/library/howto.php">APIDOX howto</a>
+  and the <a href="/documentation/library/guidelines.php">APIDOX guidelines</a>
+  for more details.
+</li>
+<li>
+  <b>Version 1.1 (July 15th 2005)</b> Added guideline elements 11 and 12.
+</li>
+</ul>
 
+<p>
 A class exists in the KDE libraries
 because it wants to be used by many KDE applications.  
 To help in that endeavor it should be fully documented to let any developer use it.  \
  New classes that are added to kdelibs must comply with this doc, all existing \
classes are grandfathered in, but need to be updated to comply if they do not.  The \
KDE library documention is based upon the Java documentation <a \
href="http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide">specification</a>. \
Follow the link for full in depth documentation about that format.   +</p>
 
 <p>These guidelines apply not only to classes in kdelibs, but
 also to libraries elsewhere (KDE PIM, for instance, has a large
@@ -34,8 +47,6 @@
 	<li><a href="#8">Avoid humour and exclamation marks.</a></li>
   <li><a href="#9">Check the spelling and grammar.</a></li>
   <li><a href="#10">Run "make apidox" before you commit any code.</a></li>
-  <li><a href="#11">Know the pitfalls of writing Doxygen comments.</a></li>
-  <li><a href="#12">Use supported tags only.</a></li>
 </ol>
 
 
@@ -194,76 +205,6 @@
   </li>
 
 
-  <li>
-    <p><b><a name="11">Know the pitfalls of writing Doxygen comments.</a></b></p>
-    <p>Common pitfalls of writing Doxygen comments include:
-    <ul>
-    <li>Forgetting to document surrounding structures.
-      <p>A method's documentation is only included if all of its surrounding
-      structural units are <i>also</i> documented. That means 
-      (for a method function) that the class, namespace and file
-      must also be documented.
-      As a guideline, every file should have
-<pre>
-/** @file This is a file. */
-</pre>
-      some form of file-level documentation.
-      Every namespace needs documentation in order
-      for classes inside it to show up; 
-      every class needs documentation for methods inside
-      it to show up.
-      </p>
-    </li>
-    <li>
-      Using @param where you meant @p.
-      <p>
-      The tag @param is for the <i>list</i> of parameters at the end
-      of the documentation of a function; @p is to be used in 
-      running text.
-      </p>
-    </li>
-    <li>
-      Using forced references.
-      <p>
-      It can be tempting -- certainly if you've written dox for 
-      other projects -- to use <tt>#method</tt> or <tt>@ref method</tt> to force a \
                reference
-      to another method somewhere. Relax, it's not needed and usually
-      causes Doxygen warnings to boot. Just name the method normally,
-      make apidox and watch the references appear naturally.
-      </p>
-    </li>
-    <li>
-      Accidentally using tags where you didn't mean to.
-      <p>
-      It's easy to slip a @ or a \ into documentation,
-      and Doxygen will immediately latch onto that as a
-      tag. For instance, referring to single characters
-      in C strings like \n and \r is hard to do
-      without using a backslash.
-      Unfortunately, Doxygen will issue a warning
-      and <i>remove the tag</i> so the Doxygenated
-      docs will not even show the characters you intended.
-      </p>
-      <p>You can use \\ and \@ to get the required
-      characters in the Doxygen output, but then it
-      looks funny in the header files themselves
-      (i.e. referring to '\\r' which isn't even legal C).
-      It's your call what is most important here.
-      </p>
-    </li>
-    </ul>
-  </li>
-  <li>
-    <p><b><a name="12">Use supported tags only.</a></b></p>
-    <p>The standard <a \
                href="http://www.stack.nl/~dimitri/doxygen/commands.html">Doxygen \
                tags</a>
-    are supported, of course. KDE uses a few others that
-    come from the Qt dox as well:
-    <ul>
-    <li><tt>\reimp</tt> "Reimplemented from Superclass"</li>
-    <li><tt>\intern</tt> "Internal use only"</li>
-    </ul>
-    </p>
-  </li>
 </ol>
 
 <hr />


[prev in list] [next in list] [prev in thread] [next in thread]