From mint-bounce@lists.fishpool.fi Wed Aug 25 16:41:29 2010 Message-ID: <4C757F5F.804@freesbee.fr> Date: Wed, 25 Aug 2010 22:38:55 +0200 From: =?UTF-8?B?VmluY2VudCBSaXZpw6hyZQ==?= User-Agent: Thunderbird 2.0.0.24 (Windows/20100228) MIME-Version: 1.0 To: mint Subject: Re: [MiNT] Kernel documentation shortcomings References: <0003e4f2.01c73262cce0@smtp.freeola.net> <1282571312.28384.4.camel@jetpack.demon.co.uk> <31B47BBF680742B49063C601C1D706D0@mercatus.local> In-Reply-To: <31B47BBF680742B49063C601C1D706D0@mercatus.local> Content-Type: text/plain; charset=UTF-8; format=flowed X-Antivirus: avast! (VPS 100825-0, 25/08/2010), Outbound message X-Antivirus-Status: Clean X-ecartis-version: Ecartis v1.0.0 Sender: mint-bounce@lists.fishpool.fi Errors-to: mint-bounce@lists.fishpool.fi X-original-sender: vincent.riviere@freesbee.fr Precedence: bulk List-help: List-unsubscribe: List-Id: X-List-ID: List-subscribe: List-owner: List-post: Content-Transfer-Encoding: 8bit X-MIME-Autoconverted: from quoted-printable to 8bit by mail.sparemint.org id o7PKfTAc001652 Jo Even Skarstein wrote: > I think it's a bad idea to maintain the API docs in a wiki. The > syscalls/API should be documented in the code itself, where the API is > implemented, using a system like Doxygen (which is already used for the > GEM bindings). Then export this to plain HTML and link to it from the wiki. Very true for the reference developer docs. However, it may be a bit difficult for the system calls because they are not always implemented as functions. And also, the TOS (and MiNT) system calls are actually an "interface". They must be implemented by some actual component (TOS, EmuTOS, FreeMiNT...). So, in the case of the system calls, maybe the interface documentation should be defined externally, for example in the Wiki (or an editable version of tos.hyp) ? Of course, programmer's guide explaining general things and examples should go into the Wiki, with references to the official documentation of the functions used. -- Vincent Rivière