[interfacekit] Re: Application Kit Tech Lead

>
>Ithamar,
>
>I'm glad you brought this stuff up (formatting interface specs) because 
>I'm currently wrestling with this myself.  I've been reimplementing 
>BArchivable & Co. to act as an example, but I've gotten sort of stuck on 
>exactly where the dividing line between functional/interface spec and 
>technical spec is and how it all relates to a) making it relatively easy 
>to use what the BeBook already provides, b) making it relatively easy to 
>create/maintain the OBOS version of the BeBook and c) making it easy on 
>the devs so they'll actually complete and maintain the docs.  So!  I'm 
>happy to hear whatever ideas you have concerning this.  My bullet-items 
>thus far:
I've been doing a more general approach to how something works in the 
interface spec - leaving out only the details which are not really necessary 
to understanding how a function/class/module works - just how it works with 
others. The tech spec, I assume, would then go over everything that the 
function/class/module does.

>* Keep as much of the documentation in source as possible (as opposed to 
>stand-alone documents)
>* Re-use as much of the current BeBook material as possible
>* Make extraction of documentation as painless and automatic as possible
BePDF also allows cut & paste on the DR3 spec, so we can pull from it, too. 
I've looked at it and it's got some pretty good stuff!

>Ideally, Dan Reinhold could do a cvs update, run an extraction tool, and 
>publish the latest version of the docs.  Something that takes 10 or 15 
>minutes, so we can have up-to-date docs once a week (at least).  If we 
>get something nice worked out, we could pass it along to the entire team 
>as a proposed standard for the whole project.
How's this grab ya - use C-style comments ( /* */ ) to mark documentation and 
C++ style for anything which should not be in the docs. It'd be easy to write 
(or find) a perl/python/shell script which could do the extraction. A 
possibility?

--DW

Other related posts: