[haiku-doc] Re: Pahe III BlockCache.dox .diff

  • From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
  • To: haiku-doc@xxxxxxxxxxxxx
  • Date: Mon, 28 May 2007 16:34:11 +0200

Hi Alan,

 I'm getting there, back from my course now! I'm still looking at the
syslog.dox. I've found a document by Axel that I'm trying to incorporate, so
it's taking me a bit longer than anticipated.

See here:


This document is quite detailed. At first I'd say: let's convert that
document to doxygen and let's just use it (with Axel's permission).
It's obviously a complete explanation of the system logger, not just a
tutorial. At the other hand, I don't know how much applications will
actually use this API. Maybe this document will be too much.

What do you think?

As how to convert this document: either we add the document as a
separate page, or we add the contents to the main content of the
syslog.dox file. The last solution is limited in the sense that you
cannot create subsections and headers. So I tend to incline to the
first one. However, I'd like to get some other thoughts on that (and
maybe we should ask Axel for permission first, and an opinion on the
cuality of this document).

Hopefully it's the correct thing to do for these documents. I personally
think we should be quite verbose where possible.

Verbosity is good to a certain extend. We should try to remain a
reference document, not a tutorial. We should also prevent
concentrating too much on little, limited things (such as API's for
very specific buses). I'm not truely convinced that this document is
not too specific.


Other related posts: