Frames

API


Class Documentation

For those of you wanting to know how Camstream is build, you can find the documentation of (most of) the classes here. All classes are documented in Qt style (which I like a lot, though Javadoc is IMO a bit better) in HTML.
The documentation is generated with Doxygen by Dimitri van Heesch. It is used in a lot of projects, including Qt itself.

This documentation, however, is not:

You can now proceed to the API main page. Although I try to keep this documentation up to date, there may still be a few bits missing.


Why?

You might wonder: "Why is there documentation of an API?" Aren't this standalone applications? Yes, but there are good reasons for including the documentation:

It's good for me

I don't work on this project full-time. Sometimes it lies there for weeks, and it's a really great help to be able to quickly browse through the class documentation to see what a function was called or what parameters it takes.

It's good for you

If you want to debug, enhance, improve or otherwise delve into the code it allows you to quickly locate the segments of code that interest you.

It looks professional

I'm a software engineer, and a professional. I therefor want not just the program to look great, but also the documentation that comes with it. Since Camstream is an open source, GPLed project the code itself is part of the application. Therefor it also deserves proper documentation. I've seen way too many open source programs which are of very high quality, but did not have any documentation on the source code itself.

This is a pity, since when there is a problem I usually need to wade through heaps of C/C++ code to find the proper function, or step through the code line by line with a debugger. Proper documentation could have saved me a lot of time.

The argument "The source code is the best documentation" is a valid one, but also a lazy one.

Some parts are reusable

It is entirely possible that you want to use some of the classes in your own projects (C++ is about reusability, after all). The documentation will surely help you in designing and maintaining your applications.

Think first, then code

Although the documentation is generated from the code, this does not mean there isn't a proper amount of thinking first. I don't hack this code, I design it (well, okay, some of the design decisions are made ad hoc). So before a single byte of code is entered I lay out the class with its semantics, variables and functions. At first, these are all just notes on a piece of paper; the inclusion of the documentation in the class code is just the last step in the process.

Of course, this doesn't mean a class won't change; they most certainly do, and the documentation is updated to reflect that. The process where the documentation is embedded in the source code makes it a lot harder to 'forget' about updating your documentation :-)

2001-05-15 - Nemosoft Unv.