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.

Local colours for Indonesian National police

As a result of the local autonomy program that commenced in Indonesia in Jan 2001, there is a concern regarding the applicability of the formalized model of security & the possibility of that being replaced by a local community-based security model. This rather informal security model is then promoted to be the only form of security used between societies & the nation. However, this model does not solve the problem because of widespread corruption, collusion, & nepotism, & the many limitations of the Indonesian National Police (Polri), a police department that has a mediocre & generalized level of service. In relation to autonomy, the effort of empowering the police units from the regional police down will bridge the gap between the people's ability to protect themselves & the limitations of those that are sworn to uphold the law. 17 References. Adapted from the source document.