Post History

One possibility on why the readers didn't find the documentation helpful may be that they are unfamiliar to the API, and the reference documentation is the *only* documentation available. 

Reference manuals are there for the people who already are familiar with the API, and only have to look up the specifics of a function. It is almost always *not* suitable for people who are completely new to the API (an exception is e.g. a collection of math functions that are independent of each other).

This is a trap that especially projects using auto-generated reference manuals tend to fall into: They think they auto-generate reference documentation, therefore their API is adequately documented. But if your *only* documentation is the reference, then your API is *not* adequately documented.

As an example, take an imaginary graphics library.

If you look at the reference manual for the `drawLine` function, then you might find something like this:

> `void drawLine(Canvas c, GraphicsContext gc, Point start, Point end)`
>
>  Draws a line on a given canvas, using the settings from the given graphics context.
>
>  Arguments:
>
>    * `Canvas c`: The canvas to draw on. If Null, the function does not draw anything, but still updates the optional graphics context passed as second argument.
>
>    * `GraphicsContext gc`: The graphics context to use. If Null, the default graphics context of the supplied canvas is used. If no canvas is given either (the first argument is Null, too), the call returns immediately without doing anything.
>
>      The graphics context is used to determine the line style and drawing mode, and optionally the start and/or end point. On return, the `initialPoint` and `currentPoint` values of the graphics context are updated as described in the next two parameters.
>
>      See the type documentation for `GraphicsContext` for details.
>
>    * `Point start`: The point where to start the line. If Null, the `currentPoint` from the graphics context is used. If not Null, the value is stored in the graphics context as `initialPoint` on return.
>
>    * `Point end`: The point where to end the line. If Null, the `initialPoint` from the graphics context is used. On return, the `currentPoint` of the graphics context is set to this value.

Now if you are familiar with the graphics library, this documentation contains everything you need. But if you are not familiar with it, it will raise more questions than answers: What is a canvas, and how do I get one? What is a graphics context? What's that thing about `initialPoint` and `currentPoint`?

Now for sure, you can find all this in the reference documentation; you'll probably start by looking up the Canvas and GraphicsContext types, which will then lead you to functions that can be used to create those types and manipulate the GraphicsContext, probably involving other concepts like devices, leading you to the documentation of the corresponding types and functions for those … basically you'll have to discover the *structure* of the API on your own.

And that's where a programmer's manual comes in: This does not tell you every detail of the API, but it tells you the high-level aspects. It presents you the key concepts of the API in a logical and easy to grasp manner, tells you which steps you have to do in which order to get to the point where you can issue drawing commands, tells you abut the most important differences between drawing on the screen and drawing in a file, etc.

Basically, the programmer's manual allows you to get familiar with the API, while the reference library tells you the details of every single function and type, assuming you are already familiar with the API.

The two manuals are different because they are for different audiences. Someone new to the API will mainly use the programmer's manual. Someone familiar with the API will exclusively use the reference manual.

And most importantly, a programmer's manual *cannot* be generated from comments on the specific functions. Sorry, you'll not get to avoid the work.