[negligible]

Hey,

I've been tasked with creating an API from one of our companies class libraries, which is something I haven't done before. For the documentation I was thinking of following an MSDN style approach and having a section for each class with it's method, properties etc, along with a code snippets displaying their use.

Is there anything else I should include? What do you hate being missing/vague?

I've not really worked with well documented API's yet.
Technically this project is an API for a 3rd companies API we utilise, it has barely any documentation and had to be reverse engineered by inspecting packets and a great deal of trail and error originally. Probably why they don't want to develop with it themselves but weird eh.

This post has been edited by negligible: 31 May 2012 - 08:49 AM

[dorknexus]

I think what you include in the documentation is pretty important. I like to see things like examples anywhere that might be confusing. The JDK documentation is wonderful for this reason because it will include a brief usage example in places where it's not easy to understand. All of their documents are interlinked very well so I can navigate through different types with ease. They also include diagrams of class/type hierarchies which is very useful in OO languages.

Are you actually writing software to wrap around this existing library, or are you writing documentation for an existing API? I'm a little confused about what you are doing.

For the documentation aspect, here are some popular API docs that you could use for inspiration:

• Java 7 API Docs
  
• Ruby 1.9 API Docs
  
• Scala API Docs

This post has been edited by dorknexus: 31 May 2012 - 09:20 AM

[tlhIn`toq]

Code snippets for each method are great. But be sure to include a good explanation of the underlying principals of the API.

I've used several OEM API's that seem to just assume you know what their designers were thinking when they build the device or the library.

• They know the camera holds the images until you call to retrieve them, but they never actually tell you that up front.
  
• They know the expected order of operation is
  
  • Make buffers
    
  • Get data as raw array
    
  • Call method to translate array to objects
  
  
• They know they do all their match as integers * 100 rather than floating point because its faster, and the coder has to divide the results before displaying them to the GUI.
  
• They know their methods used shared memory space and thus aren't thread-safe.

But they never explicitly tell you the underlying principals. You have to read through all the methods to get a feel for their design concepts.

A simple fully functioning application, with lots of in code comments/documentation. Even if its just a GUI with buttons and textboxes that report the results, or whatever is appropriate for the functionality of your library.

[Sergio Tapia]

Lots and lots of code examples of applications of your API.