[Opensim-dev] API documentation

[Alan M Webb]

Justin has a good point, but even in complicated cases, the code will tell 
us WHAT it does. The commentary is needed, in all circumstances to tell us 
WHY it does what it does. It should do it in a way that allows the reader 
to understand what else might have been done and still satisfy the 
functional requirement. The code is the implementation, the commentary 
should represent the design. So providing commentary at a functional 
(rather than statement) level is often to be preferred for this reason.

Is anybody interested in composing a formal specification of how a virtual 
world engine should behave? Such a specification would not be OpenSim 
specific, but should reflect a formal model of which OpenSim is one 
possible refinement. It's something that virtual worlds appears to lack at 
present. If anyone knows of an existing specification, I'd very much 
appreciate a pointer.

Best regards
Alan
-------------------
T.J. Watson Research Center, Hawthorne, NY
1-914-784-7286
alan_webb at us.ibm.com



From:
Justin Clark-Casey <jjustincc at googlemail.com>
To:
opensim-dev at lists.berlios.de
Date:
11/17/2008 08:48 AM
Subject:
Re: [Opensim-dev] API documentation



Mike Mazur wrote:
> Hi,
> 
> On Sun, 16 Nov 2008 19:23:00 -0800 (PST)
> Charles Krinke <cfk at pacbell.net> wrote:
> 
>> Is there any
>> reason why we cannot solicit small "comment type" patches to add
>> summaries for namespaces and classes that are currently blank to help
>> our documentation along?
> 
> I can't think of a reason. Helping with documentation is a great way to
> contribute to an open source project. Becoming familiar with the
> codebase by documenting and reading it can be a great way to become a
> developer.

+1  As far as I'm concerned, such summary documentation patches for 
classes and methods are most welcome.  Other inline 
comment patches are also good, though I think it's important not to go 
overboard where the code can speak for itself. 
For example, an extreme case would be

// Increment the number by one
number++;

-- 
justincc
Justin Clark-Casey
http://justincc.wordpress.com
_______________________________________________
Opensim-dev mailing list
Opensim-dev at lists.berlios.de
https://lists.berlios.de/mailman/listinfo/opensim-dev


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://opensimulator.org/pipermail/opensim-dev/attachments/20081117/676af979/attachment-0001.html>