Re: API style guides?

Subject: Re: API style guides?
From: Johan Lont <jlont -at- BAAN -dot- NL>
Date: Mon, 25 May 1998 16:56:59 +0200

Title: Re: API style guides?

I think you will have to define your own standards and styles for API-documentation, but I think the following could be helpful:

You'll find some standards for writing API documentation on Sun's Java homepages.

You can find a description of the details that should be present in the description of an API on the following Internet page: (http:) //java.sun.com/products/jdk/javadoc/details-of-apispecs.html .

These standards were intended for use with the Java language and the Javadoc tool. (In Java it is common to write the API documentation as special Doc comments in the source code, and convert these comments to HTML by using the javadoc tool). However, you can apply many of these guidelines to other types of API documentation as well.

For example, you'll find guidelines such as:
        A method implements an operation, so it usually starts with a verb phrase:

        Gets the label of this button.        (preferred)

        This method gets the label of this button.    (avoid) 

You can find these guidelines here:  http:
//java.sun.com/products/jdk/javadoc/writingdoccomments.html
There is also a hyperlink to examples of API documentation in HTML form.

Johan Lont

Technical Author, Baan Development BV.


Previous by Author: Re: Relational Database vs. Nonrelational
Next by Author: Documents for multiple audiences
Previous by Thread: Re: API style guides?
Next by Thread: screen capture utility with a resize function


What this post helpful? Share it with friends and colleagues:


Sponsored Ads