API documentation with executable examples

The rise of component-based software development has created an urgent need for effective application program interface (API) documentation. Experience has shown that it is hard to create precise and readable documentation. Prose documentation can provide a good overview but lacks precision. Formal methods offer precision but the resulting documentation is expensive to develop. Worse, few developers have the skill or inclination to read formal documentation. We present a pragmatic solution to the problem of API documentation. We augment the prose documentation with executable test cases, including expected outputs, and use the prose plus the test cases as the documentation. With appropriate tool support, the test cases are easy to develop and read. Such test cases constitute a completely formal, albeit partial, specification of input/output behavior. Equally important, consistency between code and documentation is demonstrated by running the test cases. This approach provides an attractive bridge between formal and informal documentation. We also present a tool that supports compact and readable test cases; and generation of test drivers and documentation, and illustrate the approach with detailed case studies. (C) 2002 Elsevier Science Inc. All rights reserved.

A case study in specification and implementation testing

Achieving consistency between a specification and its implementation is an important part of software development In previous work, we have presented a method and tool support for testing a formal specification using animation and then verifying an implementation of that specification. The method is based on a testgraph, which provides a partial model of the application under test. The testgraph is used in combination with an animator to generate test sequences for testing the formal specification. The same testgraph is used during testing to execute those same sequences on the implementation and to ensure that the implementation conforms to the specification. So far, the method and its tool support have been applied to software components that can be accessed through an application programmer interface (API). In this paper, we use an industrially-based case study to discuss the problems associated with applying the method to a software system with a graphical user interface (GUI). In particular, the lack of a standardised interface, as well as controllability and observability problems, make it difficult to automate the testing of the implementation. The method can still be applied, but the amount of testing that can be carried on the implementation is limited by the manual effort involved.

Biodiversity conservation and vegetation clearing in Queensland: Principles and thresholds

Clearing of native vegetation is a major threat to biodiversity in Australia. In Queensland, clearing has resulted in extensive ecosystem transformation, especially in the more fertile parts of the landscape. In this paper, we examine Queensland, Australian and some overseas evidence of the impact of clearing and related fragmentation effects on terrestrial biota. The geographic locus is the semi-arid regions. although we recognise that coastal regions have been extensively cleared. The evidence reviewed here suggests that the reduction of remnant vegetation to 30% will result in the loss of 25-35% of vertebrate fauna, with the full impact not realised for another 50-100 years, or even longer. Less mobile, habitat specialists and rare species appear to be particularly at risk. We propose three broad principles For effective biodiversity conservation in Queensland: (i) regional native vegetation retention thresholds of 50910: (ii) regional ecosystem thresholds of 30%: and (iii) landscape design and planning principles that protect large remnants, preferably > 2000 ha, as core habitats. Under these retention thresholds. no further clearing would be permitted in the extensively cleared biogeographic regions such as Brigalow Belt and New England Tablelands. Some elements of the biota. however, will require more detailed knowledge and targeted retention and management to ensure their security. The application of resource sustainability and economic criteria outlined elsewhere in this volume should be applied to ensure that the biogeographic regions in the north and west of Queensland that are largely intact continue to provide extensive wildlife habitat.

Generalized quasi mode theory of macroscopic canonical quantization in cavity quantum electrodynamics and quantum optics II. Application to reflection and refraction at a dielectric interface

The generalization of the quasi mode theory of macroscopic quantization in quantum optics and cavity QED presented in the previous paper, is applied to provide a fully quantum theoretic derivation of the laws of reflection and refraction at a boundary. The quasi mode picture of this process involves the annihilation of a photon travelling in the incident region quasi mode, and the subsequent creation of a photon in either the incident region or transmitted region quasi modes. The derivation of the laws of reflection and refraction is achieved through the dual application of the quasi mode theory and a quantum scattering theory based on the Heisenberg picture. Formal expressions from scattering theory are given for the reflection and transmission coefficients. The behaviour of the intensity for a localized one photon wave packet coming in at time minus infinity from the incident direction is examined and it is shown that at time plus infinity, the light intensity is only significant where the classical laws of reflection and refraction predict. The occurrence of both refraction and reflection is dependent upon the quasi mode theory coupling constants between incident and transmitted region quasi modes being nonzero, and it is seen that the contributions to such coupling constants come from the overlap of the mode functions in the boundary layer region, as might be expected from a microscopic theory.