How do you intend to document your OS?

[brain]

...as in the subject!

Personally, with my OS i intend to actually spend some time writing a proper API guide for the driver/kernel module interface, and language reference for my modified BBC BASIC language. The API guide would doxygen based, saving me typing, but the language guide would have to be typed up laboriously by hand. Of course, i could probably find an open licensed (GFDL or such) copy of a BBC BASIC reference somewhere, and simply extend it to include my own keywords, and remove any that are unsupported.

What are your own approaches to this, and anything else that you need to document that you plan to have others extend?

[Kazinsal]

I need to document. Badly.

Actually, no, I need to document properly.

Here's my problem: I tend to document sparsely while I'm coding because I don't expect to revise that code or reference it infrequently enough that I need more than IntelliSense telling me what function parameters are. I'm thinking of using the documentation generator included in Visual Studio, but the system is very XML-based and thus very messy looking at first glance, which could clutter up my source files.

Still, it's something I'm looking forward to implementing when I get home from Las Vegas tomorrow night.

[Prochamber]

For my BASIC commands and API functions I have a plain text file that had standard fields for each item, like name, description, input parameters, output parameters and notes. I do smaller regular releases and write the documentation about the functions after implementing them. It's nothing fancy but it works. Anything more complex and I probably wouldn't have any time/enthusiasm to do it. I make sure to write about commands about implementing them or they'll never get done.

Eventually I plan to put it into HTML documentation.

[AJ]

For OS Development, I always use Doxygen - mainly because it adds such little work. For application development, I tend to use C# and use the built-in XML documentation.

Cheers,
Adam

[Mikemk]

I'll find a while if i ever get to the first release.

[Owen]

I'm not really doing much OS development work at the moment; I seem to have succumbed to the "curse of the C library" like Solar before me. So, I'll comment on what I'm doing for PDCLib.

Well, like good C libraries... man pages. Because I'm apparently a lunatic of the sorts rarely found outside the BSD developer communities, Man pages written directly using the apporpriate ROFF macros

[thepowersgang]

There was a period when I had pretty darn good doxygen documentation for my kernel API, but that's lower quality nowadays. But I still put basic doxygen/javadoc headers on all my functions, just they're never processed.

As for other APIs, mostly they're source documented (i.e. read the source you ning-nong)

[Combuster]

NaturalDocs user - better than doxygen for my practical needs. The documentation is built together with the nightly build run, so it stays pretty much up to date.

[AJ]

Hi,

I've just had a look at NaturalDocs and it does look a nice format compared to Doxygen.

Cheers,
Adam

[dozniak]

I've just had a look at NaturalDocs and it does look a nice format compared to Doxygen.

It looks promising, but there's still no full language support for C/C++. It'll have to wait, at least for me.

[JackScott]

For API documentation, I use Doxygen. I never actually bother building the documentation HTML files (though my Makefile does have an option to do so) but I have it because my IDE (Netbeans) uses the Doxygen information as hints to do code hinting and pop-up documentation.

There are all sorts of other documentation that you need for an operating system though: kernel developers documentation (only part of which is the API documentation), application developers documentation (with another set of API documentation in that), and then finally user documentation for the poor souls who eventually have to use the OS. Of course, I haven't got around to writing any of that.