<html>
<head>
<title>Camstream API</title>
<link rel="stylesheet" href="../tech.css" type="text/css">
</head>
<body>
<p><a href="index.html" target="_top">Frames</a></p>
<center><h1>API</h1></center>
<img src="c-logo.png" width=150 height=150><br clear=left>
<h2>Class Documentation</h2>
<p>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.<br> The documentation is generated with <a
href="http://www.stack.nl/~dimitri/doxygen/index.html">Doxygen</a> by
Dimitri van Heesch. It is used in a lot of projects, including Qt itself.
<p>This documentation, however, is <b>not</b>:
<ul>
<li>a user manual;
<li>an explanation of the techniques used in datacompression and
network transmission. This is covered in a separate chapter;
</ul>
<p>You can now proceed to the <a href="html/index.html">API main page</a>.
Although I try to keep this documentation up to date, there may still be a
few bits missing.
<hr>
<h2>Why?</h2>
<p>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:
<h3>It's good for me</h3>
<p>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.
<h3>It's good for you</h3>
<p>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.
<h3>It looks professional</h3>
<p>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 <b>did not
have any documentation on the source code itself</b>.
<p>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.
<p>The argument "The source code is the best documentation" is a
valid one, but also a lazy one.
<h3>Some parts are reusable</h3>
<p>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.
<h3>Think first, then code</h3>
<p>Although the documentation is generated from the code, this does not mean
there isn't a proper amount of thinking first. I don't <i>hack</i> this
code, I <i>design</i> 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.
<p>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 :-)
<h6><i>2001-05-15 - Nemosoft Unv.</i></h6>
</body>
</html>
