Subversion Repositories tendra.SVN

<?xml version="1.0" standalone="no"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"

  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<!--

  $Id$

-->

<book>

	<bookinfo>

		<title>Adding new APIs with tspec</title>

		<corpauthor>The TenDRA Project</corpauthor>

		<author>

			<firstname>Kate</firstname>

			<surname>Flavel</surname>

		</author>

		<authorinitials>KF</authorinitials>

		<pubdate>2006</pubdate>

		<copyright>

			<year>2006</year>

			<holder>The TenDRA Project</holder>

		</copyright>

	</bookinfo>

	<chapterinfo>

		<abstract>

			<para>

				<!-- TODO who this document is for -->

			</para>

			<para>

				<!-- TODO

				This is not a generic tspec guide; it's specific to

				how we use tspec within TenDRA.

				For the general usage guide, see user/guides/tspec.

				-->

			</para>

		</abstract>

	</chapterinfo>

	<!--

		TODO all titles are just sketches to remind me: they need replacing

		TODO add @id to sections and chapters

	-->

	<chapter id="introduction">

		<!-- TODO apparently this should be a <preface> -->

		<title>Introduction</title>

		<sect1>

			<title><!-- TODO what an API is --></title>

		</sect1>

		<sect1>

			<title><!-- TODO what it's for --></title>

		</sect1>

		<sect1>

			<title><!-- TODO how they're specified --></title>

			<!-- TODO -->

			<para>

				<!-- TODO link to the tspec guide and recap its explanation -->

			</para>

		</sect1>

		<sect1>

			<title><!-- TODO where they live in the source --></title>

			<!-- TODO. -->

			<para>

				<!-- TODO go have a look at the existing ones. -->

			</para>

		</sect1>

		<sect1>

			<title><!-- TODO Purpose of this document --></title>	<!-- Not who it's for -->

			<para>

				<!-- TODO A guide to the process of adding a new API to TenDRA with tspec. -->

			</para>

			<para>

				<!-- TODO

				This guide should introduce the process involved;

				how to go about the whole thing, what things should

				inherit from where and why, and how to perform testing.

				-->

			</para>

		</sect1>

	</chapter>

	<chapter>

		<title><!-- TODO Why --></title>

		<sect1>

			<title><!-- TODO daunting --></title>

			<para>

				Adding new APIs can be rather daunting for several reasons:

			</para>

			<!-- TODO -->

			<para>

				<!-- TODO They can be huge -->

			</para>

			<para>

				<!-- TODO they're confusing -->

			</para>

			<para>

				<!-- TODO even when they're not confusing, they're complex:

				there're fun exceptions like "the value of the limit

				may differ from those given in this header ..."

				which require special cases -->

			</para>

			<para>

				<!-- TODO Figuring out which bits inherit from existing APIs is

				confusing (explain inheritance) -->

			</para>

			<para>

				<!-- TODO It's unlikely that tspec is familiar -->

			</para>

			<para>

				<!-- TODO not adding them is easier (see Temptations

				for the easy way) -->

			</para>

		</sect1>

		<sect1>

			<title><!-- TODO Why bother at all? --></title>

			<!-- TODO -->

			<para>

				<!-- TODO good question. specs aren't required -->

			</para>

		</sect1>

		<sect1>

			<title><!-- TODO Why be so pedantic about inheritance? --></title>

			<!-- TODO -->

			<para>

				<!-- TODO

				Why bother with inheritance?  - also good...

				you can write the same thing without inheritance.

				-->

			</para>

			<para>

				<!-- TODO

				recap what inheritance is first

				-->

			</para>

			<para>

				<!-- TODO

				One argument is to centralise code, and 

				mistakes (either in your API or the existing ones)

				This helps test the existing ones.

				-->

			</para>

			<para>

				<!-- TODO

				Motivational speech: it's very easy to make something

				here that works; it's very tedious to make it correct

				and since it's a specification, it *has* to be correct,

				or there's no point

				-->

			</para>

		</sect1>

		<sect1>

			<title><!-- TODO Temptations for the easy way --></title>

			<!-- TODO -->

			<para>

				<!-- TODO

				For example, temptation and POSIX3:

				- explain temptation

				-->

			</para>

			<para>

				<!-- TODO

				I'm going through them one by one 

				and checking... instead of (incorrectly) editing the POSIX1 

				definition, those should be under POSIX3 (which is incomplete) 

				-->

			</para>

			<para>

				<!-- TODO

				I'm trying to really check everything that goes on here,

				so we don't accidentally break unrelated things

				(unrelated things being machine definitions, or other specs)

				-->

			</para>

		</sect1>

		<!-- TODO -->

		<para>

			<!-- TODO

			In conclusion:

			Explain that this is tedious, pedantic, difficult to get

			right, and also very important that it *is* done correctly.

			That's pretty much the worst case for a task on all parts.

			-->

		</para>

	</chapter>

	<chapter>

		<title><!-- TODO Looking at your API --></title>

		<para>

			<!-- TODO

			Discuss about your API:

			What API are you adding?

			-->

		</para>

		<sect1>

			<title><!-- TODO is it a viable candidate at all? --></title>

			<!-- TODO -->

			<para>

				<!-- TODO

				What APIs are suitable for inclusion into the base, and what

				aren't (i.e. if it's important enough to come with your OS's

				base, and has a stable standard, we should probably include

				it - if it's a moving target or work in progress, we probably

				shouldn't). This should also mention something about which

				language are supported.

				-->

			</para>

			<!-- TODO -->

			<sect2>

				<title><!-- TODO is it standardised and no longer in flux --></title>

				<!-- TODO -->

			</sect2>

			<sect2>

				<title><!-- TODO is it useful to people other than yourself? --></title>

				<!-- TODO -->

				<!--

					TODO: it would be interesting to let users specify their

					own APIs privately (or perhaps make a community resource

					of APIs for projects somehow. Perhaps this should be a ticket

				-->

			</sect2>

		</sect1>

		<sect1>

			<title><!-- TODO How it relates to other APIs --></title>

			<!-- TODO -->

			<para>

				<!-- TODO

				When to inherit, and when to write from scratch (i.e. write

				from scratch if the specification independently states the

				same thing as another by coincidence, as opposed to

				explicitly stating that it should correlate with (and defer

				to!) a parent specification)

				-->

			</para>

			<sect2>

				<title>Inheriting APIs</title>

				<para>

					This is the usual case: an API that builds on previous

					standards. For example, POSIX builds on ANSI.

				</para>

				<!-- TODO explain more -->

			</sect2>

			<sect2>

				<title>Standalone APIs</title>

				<!-- TODO -->

				<para>

					<!-- TODO

					If it's an entirely self-standing API,

					*sure* it's appropriate to add? (it might be)

					-->

				</para>

			</sect2>

		</sect1>

	</chapter>

	<chapter>

		<title>Implementation Approach</title>

		<!-- TODO -->

		<para>

			<!-- TODO

			Implementation details. Link to the tspec guides

			sections here.

			-->

		</para>

		<sect1>

			<title>Sequence of Implementation</title>

			<!-- TODO -->

			<para>

				<!-- TODO

				How not to be overwhelmed by the sheer size of something

				like POSIX3. Some dicipline is required here: do not get eager.

				-->

			</para>

			<para>

				<!-- TODO

				APIs can be large; you can optimise work flow by grouping

				related tasks. Less switching between modes gives faster

				implementation time and less mistakes

				-->

			</para>

			<para>

				<!-- TODO

				One thing that's helping me here is to tackle strictly only

				the really simple files first, leaving the complex ones for

				later. The rough pattern there is to finish working on lots

				of simple ones all at once, and then to spend a longer time

				working through each complex file individually. This also

				helps keep up motivation by cutting down the list of incoming

				things!

				-->

			</para>

			<para>

				<!-- TODO

				i was doing all the headers which only define constants, first

				then all the ones which inherit things from previous 

				specifications (this is very tedious to get right)

				limits.h was way down that list

				-->

			</para>

			<para>

				<!-- TODO

				but we can do just the things needed, first, if you like

				think about customer demand: we can provide it without

				damaging our project. maybe even partial headers

				(comment them)

				-->

			</para>

		</sect1>

		<sect1>

			<title>Implementing Inheritance</title>

			<!-- TODO -->

			<para>

				<!-- TODO

				How our inheritance is structured at the directory level

				(with +IMPLEMENT), and what qualifies for this.

				-->

			</para>

			<para>

				<!-- TODO

				How our inheritance is structured within files (with +USE),

				and what qualifies for this.

				-->

			</para>

		</sect1>

	</chapter>

	<chapter>

		<title>Testing</title>

		<!-- TODO -->

		<para>

			<!-- TODO

		 	How to test your abstract implementation.

			Not easy, and tempting to skip!

			-->

		</para>

		<sect1>

			<title><!-- TODO often not practical to fully test --></title>

			<!-- TODO -->

			<para>

				<!-- TODO

				(i.e. to find/make a perfect implementation)

				So instead the trick is to be as thorough as possible

				without neccessarily being comprehensive.

				-->

			</para>

		</sect1>

		<sect1>

			<title><!-- TODO often not practical to test fail cases --></title>

			<!-- TODO -->

			<para>

				<!-- TODO

				(there are lots)

				-->

			</para>

		</sect1>

		<sect1>

			<title><!-- TODO What if one of your test systems doesn't actually conform? --></title>

			<para>

				<!-- TODO

				This can be confusing and annoying. Don't panic!

				It's easy to miss this, and tempting to handle it

				incorrectly. But we have a method to express this properly:

				-->

			</para>

			<para>

				<!-- TODO

				It's the implementation at fault, not the spec, so state

				it there: add __WRONG, etc to machines

				-->

			</para>

		</sect1>

	</chapter>

	<chapter>

		<title><!-- TODO Interesting Points from a Worked Example --></title>

		<para>

			<!-- TODO

			e.g. POSIX3. introduce the background to why we added this.

			(getting hold of the POSIX2 spec was annoying;

			if you want to do this; you need it to see where 

			to inherit and where not to and to double-check)

			-->

		</para>

		<para>

			<!-- TODO

			see POSIX2/limits.h - that just imports from POSIX1, 

			but limits.h changes significantly for v3

			-->

		</para>

	</chapter>

	<chapter>

		<title>Related Documents</title>

		<!--

			TODO looks like the other documents need a little cleanup

			for their siblings here, too.

		-->

		<para>

			<!-- TODO both of these should be hyperlinks:

			* tspec guide

			* where the apis live in the source. go explore!

			-->

		</para>

	</chapter>

</book>