From mint-bounce@lists.fishpool.fi Wed Aug 25 16:58:20 2010 Message-ID: <4C758352.7050002@online.no> Date: Wed, 25 Aug 2010 22:55:46 +0200 From: Jo Even Skarstein User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.1.11) Gecko/20100713 Thunderbird/3.0.6 MIME-Version: 1.0 To: mint@lists.fishpool.fi Subject: Re: [MiNT] Kernel documentation shortcomings References: <0003e4f2.01c73262cce0@smtp.freeola.net> <1282571312.28384.4.camel@jetpack.demon.co.uk> <31B47BBF680742B49063C601C1D706D0@mercatus.local> <4C757F5F.804@freesbee.fr> In-Reply-To: <4C757F5F.804@freesbee.fr> Content-Type: text/plain; charset=UTF-8 X-ecartis-version: Ecartis v1.0.0 Sender: mint-bounce@lists.fishpool.fi Errors-to: mint-bounce@lists.fishpool.fi X-original-sender: joska@online.no 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 o7PKwJrC020157 On 08/25/2010 10:38 PM, Vincent Rivière wrote: > 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) ? The point in having the API docs in the code itself is to force the developers to keep the API docs up to date whenever there's a change. External docs won't be updated. > 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. Agree. Jo Even