Documenting the Source

As you maybe know I have a new job since last December and I’m working on
Samba4 now. Samba4 is a monster so I’ve asked for some simple tasks to get
started. The task was to migrate some code to a new Samba library called
tsocket. The problem was I didn’t know what to do and how. Some functions
of the API were documented but not all. So I had to guess from the names
what the function is doing and read the code to understand it. Then I’ve
started to work with the interface and I had to look again the the code to
find out possible return values. In the end I spent a lot of time jumping
through the source code to find out the return values for the functions.

If the API would be completely documented I could get my work done a lot of
faster so I simply started to document it cause I had to understand it anyway.
I’ve decided to write the documentation with doxygen and put it in the header
file, so that people who use the PAI always have the documentation with them.

After I finished it, started to work on the source code again and got some
things working as I was able to understand the API of the library. Then I
crossed the next undocumented API of a library. Ok, it wasn’t undocumented it
had a text file describing everything but having doxygen documentation is much
nicer than a text file. So I’ve started to document talloc from Samba4 with
doxygen.

The talloc API uses macros for a lot of things to make debugging easier or
to hide things you’re doing from the user. However if you document a macro
than normally you want that it looks like a function. To be able to do that
with doxygen you have to use a little trick. As doxygen has a C preprocessor
built in you can create a define for a doxygen mode. That’s what I’ve done in
the config file and all you need to do in the source code is to use it with
#ifdef.

#ifdef DOXYGEN
/**
* @brief Create a new talloc context.
*
* The talloc() macro is the core of the talloc library. It takes a memory
* context and a type, and returns a pointer to a new area of memory of the
* given type.
*
* The returned pointer is itself a talloc context, so you can use it as the
* context argument to more calls to talloc if you wish.
*
* The returned pointer is a "child" of the supplied context. This means that if
* you talloc_free() the context then the new child disappears as well.
* Alternatively you can free just the child.
*
* @param[in] ctx A talloc context to create a new reference on or NULL to
* create a new top level context.
*
* @param[in] type The type of memory to allocate.
*
* @return A type casted talloc context or NULL on error.
*
* @code
* unsigned int *a, *b;
*
* a = talloc(NULL, unsigned int);
* b = talloc(a, unsigned int);
* @endcode
*
* @see talloc_zero
* @see talloc_array
* @see talloc_steal
* @see talloc_free
*/
void *talloc(const void *ctx, #type);
#else
#define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
void *_talloc(const void *context, size_t size);
#endif


So start to document your API. What you get well be something like this and other will love it!