[haiku-doc] Re: Saying 'Hi' and API docs

  • From: John Scipione <jscipione@xxxxxxxxx>
  • To: haiku-doc@xxxxxxxxxxxxx
  • Date: Tue, 15 Nov 2011 14:49:34 -0500

I just saw your post and so joined the haiku-doc mailing list to respond

> If I wanted to help writing API documentation (the "Haiku Book") for Haiku, 
> how would I get started?

Well the very first thing you want to do to install Doxygen and git on
your system if you haven't already done that. The best version of
Doxygen to use is 1.7.3 since that is what is used on the server to
automatically build the documentation, but, the latest one should work
fine too.

Next grab the Haiku source from git by running:

git clone git://git.haiku-os.org/haiku

in some directory you want to work in. (note it will automatically
create a haiku/ subdir for you)

If you just want to write documentation then you don't need to worry
about building the operating system and running it so you don't have
to go through the steps of getting the buildtools running or the
pre-requisite software. If you want to build the OS as well follow the
guide here: http://haiku-os.org/guides/building to get it running.

The existing documentation is found in the docs/user/ directory in the
source tree. There are a number of folders located there for each kit
and topic such as interface/ app/ storage/ etc. Note that we don't do
documentation directly in the source files in Haiku, instead the
documentation is separated out into the docs/user directory. You can
look at the .dox files located there to get a feel of what the
documentation files should look like.

Next figure out the class that you want to document, you can look at
the BeBook here:
http://haiku-os.org/legacy-docs/bebook/ClassIndex.html To get a list
of classes from BeOS 5, most of which are also in Haiku or you can
browse through the source tree in src/kits/<kitname> (for the cpp
files) and headers/os/<kitname> (for the header files) to find the
list of classes in Haiku.

Note, do NOT copy from the BeBook. We do not have the legal rights to
create modified versions of it so you can use it for reference only!
Copying from the BeBook is plagiarism and could get us into a lot of
trouble. If you see that someone else has plagiarized word-for-word
from the BeBook you should make sure to update that documentation with
something original. Hopefully nobody has done that.

Once you have found a class that you want to document add a filed
called Classname.dox in the appropriate kit directory under docs/user.

As an example let's say that you want to document the BPath class
which is in the storage kit. Create a file named Path.dox under
docs/user/storage (don't include the leading B in the filename).

The "Documenting the API" Page in the Haiku Book located here:
http://api.haiku-os.org/apidoc.html gives a really good overview of
how to fill out the file but here is the basic process:

Open up the documentation file that you created (Path.dox) as well as
the corresponding source file (src/kits/storage/Path.cpp) and header
file (headers/os/storage/Path.cpp) for reference.

At the very top of the documentation file, add a header like so:

/*
* Copyright 2011 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
*               Authors name, authors email@xxxxxxxxxx
* Corresponds to:
*               /trunk/headers/os/support/Path.h  rev 43272
*               /trunk/src/kits/support/Path.cpp  rev 43272
*/

I usually copy any authors from the source or header files if there is
documentation to copy in those files (for instance I see there is some
documentation already in src/kits/storage/Path.cpp), otherwise just
add your own name and email to the Authors list. You can choose to
copyright the file to yourself if you wish, but we'd prefer if you
would assign the copyright to Haiku, Inc. as it makes things easier to
manage in the long run.

Most every section is separated by two newlines so put two newlines
after the header and then put in a \file command like this:

/*!
        \file Path.h
        \brief BPath class definition.
*/

These lines are very important, without them, none of the
documentation you write below will get generated!

Now you are going to want to look at the header file.

Add another 2 newlines and then add documentation for any enums,
structs, etc. that appear at the top of the file. Sometimes there are
none of these like in the case of BPath.

Add another 2 newlines and then add the class documentation.

/*!
        \class BPath
        \ingroup support
        \ingroup libbe
        \brief Brief description of what the class does.

        Detailed description of what the class does. Generally I give an
outline of the methods
        available in the class here so you might want to wait on this
until the rest of the
        documentation for the class is finished before filling this
out. Also code examples sometime
        go here like this:

\code
       code goes here
\endcode
*/

You are now done with the header file and now want to refer to the
source file. In the source file go through the methods one by one and
add a documentation block for each method. The first methods in the
file are (almost) always the constructor and destructor methods. Add a
block that looks like this for each constructor:

/*!
        \fn BPath::BPath()
        \brief Creates an uninitialized BPath object.

        Detailed description goes here.
*/

After the constructor and destructor methods you document each method like this:

/*!
        \fn status_t BPath::SetTo(const entry_ref* ref)
        \brief Reinitializes the object to the filesystem entry specified by the
                given entry_ref struct.

        \param ref the entry_ref

        \returns A status code.
        \retval B_OK The initialization was successful.
        \retval B_BAD_VALUE \c NULL \a ref.
        \retval B_NAME_TOO_LONG The pathname is longer than \c 
B_PATH_NAME_LENGTH.
        \retval B_ERROR other error codes.
*/

Note that you want to copy the method declaration from the source file
(or the header file) in the \fn line for each method (this is how
doxygen knows what method you are talking about).

The most important things to document are a good brief description and
document each parameter and return value. Note that many methods
return a status code. In those cases you want to try to document what
each return code means with a \retval like in the example above. This
is not always easy to do though since methods call methods call
methods which return return return so it can be hard to figure out all
the cases. Do your best.

A good brief description is sometimes helpful as well. You can use the
\remark \note \warning and \attention commands to call out important
pieces of information visually. \remark is for the least important,
\attention is the most important.

Repeat this process for each method in the file.

Once you have documented the whole thing, you are going to want to
group related methods together. To do this add blocks before and after
a group of methods like this:

/*!
        \name Group Name
        Detailed description of how the methods are related.
*/


//! @{

<documentation of related methods goes here>

//! @}

You may need to re-organize the methods a bit to put them in related
groups, but most of the time the methods are in a pretty good order
right from the source.

To build the Haiku Book just run 'doxygen' from the docs/user
directory. You'll get a bunch of warning messages from other class
documentation that we can't fix right now and you might get a few from
the documentation that you added as well. If you do, fix those.

To see the html output of your class open the
haiku/generated/doxygen/html/index.html file in your favorite Web
Browser. You should see your new class documentation there somewhere.
For example click on the Support kit link and a link to BPath should
show up in the table.

Once you are happy with the output and you want to submit the result,
create a ticket of type 'enhancement' in category 'documentation' on
trac (http://dev.haiku-os.org/) and attach the .dox file to it. One of
the many dev's interested in the documentation (possibly me) will take
a look at the file, comment on the ticket, or if it is acceptable,
just commit the result.

Good luck,

John Scipione

Other related posts: