OpenLayers API Documentation vs. Developer Documentation

Question

The OpenLayers web site provides two sets of reference documentation:

• API Docs: http://dev.openlayers.org/apidocs/
• Developer Documentation: http://dev.openlayers.org/docs/

For most classes, the API Docs contain a small subset of what is in the Developer Documentation. I find that I usually can't get much done using just the features described in the API Docs, so I use the Developer Documentation (and I read the source and examples).

What is the official distinction between these two documentation sets? Do the API Docs describe interfaces that are expected to be stable? Am I risking future breakage if I use features described only in the Developer Documentation?

Answer 1

I must edit my response to correct a little bit. Related to OpenLayers there are several main documentations:

1 - A wiki like one

2 - API documentation

3 - Developer documentation

4 - Last version/trunk API documentation

5 - Last version/trunk Developer documentation

The API documentation is intended describe the stable details of the API, while the Developers documentation point to other details which are needed when developing OpenLayers applications.

" There are two types of properties/methods in the OpenLayers code: One set is the set of API Methods and properties. There are also additional internal properties which are not exposed to the API. Javascript does not have private members, so there is no technical limitation to using these non-documented methods in Application code. However, while we make every effort not to change APIs between releases, methods and properties which are not explicitly declared as API Methods may change in minor releases.

The documentation above "(the API doc 2 and 4)" only includes the API Methods. Full developer/internal library documentation is also available below "(3 and 5)", but methods which are not available in the API documentation above can not be depended upon to stay the same between releases. If you use methods included in these docs, you may have to make modifications in your application code to run between minor releases of OpenLayers."

GOOD ANSWER : You should rely on the API docs of the latest release, link from point 2, to be sure your code is relative safe over the new versions.

WRONG ANSWER <>

My actual correct response is based on. There is a similar discussion here.