A crash course in inline source code documentation with Doxygen

BodySo I'm sure a number of you out there were a bit skeptical as to whether or not I'd be able to churn out two Doxygen newsletter articles in a row (I sure didn't think I'd manage :). Well, just to spite all of us non-believers, here I am with a shiny new tutorial on documenting your source code with Doxygen. The things I'm going to cover here are just the basic meat-and-potatoes parts of Doxygen that I use on a day to day basis; for anything else, please consult the online Doxygen manual; it's really quite handy :).

Pruning the / tree

Body:  *** Warning - this editorial may contain concepts and ideas disturbing to Unix purists!*** First, let me start out by stating that I use Unix (Solaris) almost every day. While I am not the master of all things Unix, I have a better than average knowledge of it, I like to think. I like a great many things about Unix. Pipes are probably the most useful concept I have ever seen in computer science.

I Will Survive

BodyIt's not something that might happen in a rare circumstance, something that can be neglected in the design of your media application, but something that will happen as soon as the user hits that big inviting button on front of the Media preference panel - the media_server quitting while you rely on it and the connections you have established with your own and other media nodes. So, for your programs to survive this situation, is quite desirable.

Some vague ideas...

Body:  Late at night, beating my brains for yet another newsletter article, my eyes were drawn to a notebook nearby my desk. This notebook contains my ideas that I brainstorm for future versions of OBOS. One of the complaints that people have is that R1 as we have defined it has no "future". It doesn't do anything beyond recreate what Be did and that we should aim higher for our first release.

Unit Testing, Part Deux

So, I'm sure you're all dying to know about the new grand unified CppUnit testing framework we have. What? You haven't heard of it? Color me unsurprised. :-)

Part I — Running Tests

For those of you who are purely interested in helping us out by running the tests on your own computer, this section is for you.

First off, you'll need to slurp a copy of our repository onto your computer. Next, you'll need to build the entire tree (technically you don't need the *whole* tree, but it's easier on me if you just build it all; that way I don't have to list off all the targets you'd need to specify :-). For those who are unsure of how to do this, get a copy of our development tools off the Download page, do an anonymous checkout of our repository (check out Getting and Building the Haiku Source Code for details), run ./configure from the current/ directory, run jam from the current/ directory, and go watch The Godfather (possibly all three of them) while everything builds.

Optimization can be your friend

BodyOptimization is one of those topics that everyone thinks that they understand a little about, but is often surrounded by platitudes, mystery and rumour. I want to talk a little about when to optimize, why one should optimize and some of the more successful techniques of doing so. Keep it simple The first rule of optimization is, "Don't". As Extreme Programming says, "Do the simplest thing that will work". If you are working in an OO language, this is often fairly easy because of information hiding.

Hello kernel? You have a syscall from userland!

Note: this article was written by Daniel Reinhold.

One of the features of modern operating systems is the ability to separate application code from the critical code that implements the core of the system. Regular applications run in user mode (often referred to as userland) which means that they cannot directly manipulate the vital system data structures. This makes everything much more stable -- buggy apps may crash and burn themselves, but they can't bring down the rest of the system.

The flipside to this protection is that userland code is walled off from the kernel code. This means, for example, that your application cannot directly call a kernel function. But the kernel implements many useful services that most apps would like to take advantage of. Indeed, that is one of the main purposes of the kernel -- to abstract all those icky underlying hardware details and provide a clean, consistent interface for applications. So how does all this useful interface ever get called and used?

My First OpenBeOS Build

Intro Recently, David Reid reported that the OpenBeOS kernel source tree had been amended to fit its new environment after forking from NewOS. The jam scripts had been written, tweaked, and tested, and the new kernel was now capable of being built. He even included a picture of his computer booting from the freshly created floppy. While I was happy to report this, I hadn't actually tried to do a build myself.

It should just work

BodyI had a lot of company this weekend — it was really our first time entertaining in the new house (other than an occasional friend dropping by). I like to think that my friends are a fairly intelligent group. Birds of a feather and all. My friends often come to me for help with their computer "issues", despite the fact that I haven't run Windows as my OS of choice since 1996.

Device driver basics

BodyDevice drivers are difficult to write. Understanding the hardware can be the hardest part. Often the documentation is hard to read and understand because it is written from a hardware designer's perspective (that is, if you can get the documentation -- many manufacturers are very reluctant to give it out). Drivers work directly with the kernel - a bad pointer can crash the whole OS. And, finally, you can't use warm and comfortable debugging tools, since you are working in the kernel.