Originally published by Robert Beisert at fortcollinsprogram.robert-beisert.com

Working with Poor Documentation: Options are Limited…

If it hasn’t happened to you yet, it will:

You’re working with library code – say, GNUTLS. You’ve dug around and installed all the prerequesites, and the libraries are all set up. You’re all ready to get to work…

But the documentation doesn’t match the headers you have. It turns out that all the documentation matches the newest version of the library, which you can’t get with apt. So you install the newest version from scratch – no problem.

Then it’s time to get to work. Unfortunately, there isn’t much example code available, so you have to figure it out from the sources. And the sources you have, well…

They suck.

Only some of the functions are fully documented, and they use terms and structures that you’ve never seen before. You have to guess which page of documentation has the function you want, but it’s a toss-up how the internals actually work. Do you pass in a pre-allocated buffer, or can the function allocate the space required – it’s ambiguous from the wording you can understand.

There are basically two ways to deal with this scenario:

Open source Method – Get the Source

If you’re reasonably skilled at reading code (which you should be), you can pull the sources and walk through them. With Ctags, this is a fairly managable solution:

  1. Pull the sources
  2. Run ctags in the base directory
  3. Use vi -t <function_name> to find a function you’re concerned about (from the headers)
  4. Using ] and ^t (CTRL-T), walk through until you’re satisfied
  5. Experiment with what you find

This method has a steep learning curve on the library as you learn where functions tend to live and how they string together, but with a few test programs you can usually get whatever you’re looking for. This is what I’ve had to do working with gnutls, which will be the subject of a few posts in the near future.

This method also allows you to de-obscure typedef-ed structures, which can be valuable for figuring what values you’re working with and how they fit together. Wherever possible, this is the best solution to a bad scenario.

Closed source method – experiment

This is the worst-case scenario. Depending on how bad the documentation is, it might be worth forgoing it entirely, which means working with a black box. (Fortunately, I’ve not yet had to deal with this scenario, but they do come up).

You will build small test programs. Lots of small test programs, each testing a different piece of the larger puzzle.

You will run gdb over everything that faults for any reason.

You will dig through all the headers looking for functions to play with, and you will play with them.

It takes a long time, and you’re never 100% sure that your solution is the best one, but at least you can get a functional program in the end.

Prevention

There’s no good way to redeem poorly-documented code outside of documenting it yourself, but you can prevent others from having to struggle this way:

DOCUMENT EVERYTHING

Leave breadcrumbs in your sources so that others can follow the logic more easily.

Use a tool like Doxygen, which produces useful HTML documentation and leaves useful commentary in your sources and headers.

If possible, make your sources open and available. If not possible, double-down on your available documentation to head off all the questions that users WILL ask.

Provide examples of common and uncommon uses for your functions. Ideally, you want the examples to cover every function in your library and explain the functionality and purpose of each structure.

And, very importantly, use a standard convention for naming all your functions and structures.

photo by: