Sugar Labs

Changes

Documentation Team/API Documentation (view source)

Revision as of 14:21, 14 June 2008

1,363 bytes added ,  14:21, 14 June 2008
m
editing APIDOX Basics
Line 1: Line 1:  
== Definition ==
 
== Definition ==
−
 
+
<!--
 
'''API (''Application Programming Interface'') documentation''' is documentation that applies to ''a program'' and its interfaces. It is documentation that explains to a developer who is going to work with the program, or a developer who is going to work on a program, how things work and what methods are there to call.
 
'''API (''Application Programming Interface'') documentation''' is documentation that applies to ''a program'' and its interfaces. It is documentation that explains to a developer who is going to work with the program, or a developer who is going to work on a program, how things work and what methods are there to call.
    
API documentation is sometimes called an API reference manual. It needn't ''just'' be a reference manual, though, there can be extensive additional material, like tutorials, histories, etc. In this page, we will refer to all the material that documents and explains the API of a piece of code as "apidox."
 
API documentation is sometimes called an API reference manual. It needn't ''just'' be a reference manual, though, there can be extensive additional material, like tutorials, histories, etc. In this page, we will refer to all the material that documents and explains the API of a piece of code as "apidox."
   −
Good apidox take some effort to write -- but less effort than good ''user'' documentation, since you as a developer are writing for another developer, and explaining how code works and what it is supposed to do. So your audience is clear to start with. The benefits of apidox come when someone else (or maybe even you several months later) needs to (re)use the code, or extend it. Good apidox means that someone new can show up, understand your code, and produce meaningful patches (that is, ''help'') all the more quickly. Especially for libraries, good apidox make the library usable as a black box (and that's how they should be) because all the needed documentation is available in the apidox and not hidden in the (perhaps inaccessible) C code.
+
Good apidox take some effort to write -- but less effort than good ''user'' documentation, since you as a developer are writing for another developer, and explaining how code works and what it is supposed to do. So your audience is clear to start with. The benefits of apidox come when someone else (or maybe even you several months later) needs to (re)use the code, or extend it. Good apidox means that someone new can show up, understand your code, and produce meaningful patches (that is, ''help'') all the more quickly. Especially for libraries, good apidox make the library usable as a black box (and that's how they should be) because all the needed documentation is available in the apidox and not hidden in the (perhaps inaccessible) code.
−
 
+
-->
 
== Preamble ==
 
== Preamble ==
−
 
+
<!--
 
APIDOX are what make a program accessible to other contributors. They are not essential, but they certainly help a great deal for new people who want to work on your code, or better yet, re-use it elsewhere with a minimum of modification.
 
APIDOX are what make a program accessible to other contributors. They are not essential, but they certainly help a great deal for new people who want to work on your code, or better yet, re-use it elsewhere with a minimum of modification.
   Line 16: Line 16:     
This document is going to try to prevent the apidox process from becoming exhausting, by giving straightforward tips about how to write apidox.
 
This document is going to try to prevent the apidox process from becoming exhausting, by giving straightforward tips about how to write apidox.
−
 
+
-->
 
== APIDOX Basics ==
 
== APIDOX Basics ==
   −
APIDOX are generated by the [http://www.doxygen.org Doxygen] documentation tool. This tool reads source code for your application (or library) and produces nicely formatted documentation from it. There is a good [http://www.stack.nl/~dimitri/doxygen/manual.html reference manual] available -- but let's hope to make it unnecessary to read, for basic use anyway.
+
APIDOX are generated by the [http://www.doxygen.org Doxygen] documentation tool. This tool reads the source code for your application (or library) and produces nicely formatted documentation from it. There is a good [http://www.stack.nl/~dimitri/doxygen/manual.html reference manual] available -- but let's hope to make it unnecessary to read, for basic use anyway.
    
You don't even need to have Doxygen installed to work on apidox for your application. Every few hours,  [http://api.sugarlabs.org api.sugarlabs.org] compiles apidox for all of the Sugar modules we know about. Logfiles are kept and you can see your apidox on the site, or read the error messages and fix those. ...it might not be the fastest way to write and fix apidox, but it gets the job done, and if you spend just an hour at the end of the day writing some apidox, it's sufficiently useful.
 
You don't even need to have Doxygen installed to work on apidox for your application. Every few hours,  [http://api.sugarlabs.org api.sugarlabs.org] compiles apidox for all of the Sugar modules we know about. Logfiles are kept and you can see your apidox on the site, or read the error messages and fix those. ...it might not be the fastest way to write and fix apidox, but it gets the job done, and if you spend just an hour at the end of the day writing some apidox, it's sufficiently useful.
Line 36: Line 36:  
   new features, it's still no problem to call it.  
 
   new features, it's still no problem to call it.  
 
   <nowiki>"""</nowiki>
 
   <nowiki>"""</nowiki>
−
   def increaseIQ (IQ);
+
   def increaseIQ (IQ):
 
</code>
 
</code>
   −
Note: This process is slightly different from the instruction on the Doxygen site.  Standard Doxygen comments are surrounded by /** and */.  In order to maintain with standard python documentation, api.sugarlabs.org runs a preprocessor that converts docstrings into doxygen comments.  
+
Note: This process is slightly different from the instruction on the Doxygen site.  Standard Doxygen comments are surrounded by /** and */.  In order to maintain compatibility with standard python documentation, api.sugarlabs.org runs a preprocessor that converts docstrings into doxygen comments.  
    
For proper apidox, you need to document every "thing" in your program. "Things" here are: sugar modules, python packages, python modules, classes, functions, and  variables. Complete apidox looks something like this:
 
For proper apidox, you need to document every "thing" in your program. "Things" here are: sugar modules, python packages, python modules, classes, functions, and  variables. Complete apidox looks something like this:
    
<code>
 
<code>
−
   <nowiki>"""</nowiki>
+
   # \file example.py
−
   Module for ControlPanel related classes 
+
   # \brief An example Python program.
−
  <nowiki>"""</nowiki>
  −
 
   
    
 
    
−
   /** Wrapper for a TCP/IP socket */
+
   # Demo class
−
  class Socket {
+
  class Demo:
−
  public:
+
    """
−
     /** Constructor. Calls listen() on some random high port. */
+
    \brief A demo class, it's really just for demonstration.
−
     Socket();
+
    The detailed description of the class would appear right here.
−
   private:
+
    However, as this class is utterly useless when talking about its
−
     int fd;
+
    functionality it actually has no detailed description which is
−
  };
+
    sort of a pity, since a couple of lines of documentation would
−
 
+
    make it look like a real documentation. But as this is just an
 +
    example of how the doxygen output might look like a one-liner has
 +
    to be enough. Insert your documentation here as appropriate. You
 +
    get the idea now, don't you? If not, I can't help it but I
 +
    certainly won't type in a lot of nonsense just to make it look \em
 +
    real.  No, definitely not.
 +
    """
 +
    def __init__(self):
 +
        """The constructor."""
 +
     def foo(self, bar):
 +
        """
 +
        The infamous foo method.
 +
        There's no detailed description necessary for the \em foo()
 +
        function as everybody know what it does.
 +
        \param bar The \a bar argument is compulsory, never leave it out.
 +
        \return The \a bar input after processing by the \em foo() function.
 +
        """
 +
        pass
 +
    ## protected:
 +
     def spam(self, amount):
 +
        """
 +
        Return an amount of spam.
 +
        \param amount (\c int) The amount of spam.
 +
        \return An amount of spam.
 +
        """
 +
        return amount*"spam"
 +
   # Another demo class
 +
  class AnotherDemo(Demo):
 +
     """\brief This class is derived from the demo class."""
 +
    def __init__(self):
 +
        pass
 
</code>
 
</code>
   Line 69: Line 97:     
== Writing APIDOX in New Code ==
 
== Writing APIDOX in New Code ==
−
 
+
<!--
 
The following little checklist should get you through the worst of writing apidox.  
 
The following little checklist should get you through the worst of writing apidox.  
   Line 391: Line 419:  
[http://www.stack.nl/~dimitri/doxygen/commands.html List of supported doxygen tags]
 
[http://www.stack.nl/~dimitri/doxygen/commands.html List of supported doxygen tags]
 
:This is a list of all available documentation tags of doxygen, from the official site. Note that the list uses a backslash in front of a tag, while this page always used the at sign. Both are allowed, but for KDE you should use the at sign to stay consistent within KDE.
 
:This is a list of all available documentation tags of doxygen, from the official site. Note that the list uses a backslash in front of a tag, while this page always used the at sign. Both are allowed, but for KDE you should use the at sign to stay consistent within KDE.
−
 
+
-->
 
[[Category:Documentation]]
 
[[Category:Documentation]]
Dfarning
2,751

edits

Retrieved from "https://wiki.sugarlabs.org/go/Special:MobileDiff/6161"