As a user, you use API for certain purposes. You have certain goals you want to achieve, and the API is a tool that should help you achieve them.

Your problem is, how to achieve these goals.

Think of API "hardwareToolbox", which is a common toolbox in your garage. There's a hammer, there's a set of wrenches, a screwdriver, there's a hacksaw and an electric drill. Each of them are classes that have their methods. You also have nails, screws, screw anchors, etc. (all provided by right Factory objects.)

You want to hang a picture on the wall. You have no clue how to do it.

The right procedure is to drill the hole in the wall, put a screw anchor in, using a hammer, and then screw a screw in. As the user you know you need a screw in the wall, but not much more beyond this.

Now let's look at your documentation.

Class Electric_hammer_drill. Makes holes.
@methods : drill, hammer.

method drill: Makes holes in material that doesn't need hammering
@params : tool, depth, direction
@return : hole

method hammer: Makes holes in material that needs hammering
@params : tool, depth, direction
@return : hole

Class Hammer. Applies kinetic impulse to objects.
@methods : hit.

method hit: Applies kinetic impulse to object
@params : object, strength, location

Factory Screw_anchor: anchors screw to wall.
@params : inner_diameter, outer_diameter, length

Factory Screw: Binds things together
@params : diameter, length.

Class Screwdriver: Turns screws.
@methods turn

Method turn: Turns screw.
@params : direction, rotations, hole, screw.

...and about 40 other tools and items you don't need.

Do you see where I'm going?

The user will deduce: I need a screw in the wall. To move screw I need screwdriver. Screwdriver requires hole. To make hole I need the drill. By a lot of trial and error I discover wall requires hammering, and a masonry bit for a tool to obtain a hole. (or I just drill one with wood bit, cursing the inefficiency of the API.) Then I try to fit the screw and it doesn't hold, and I'm all frustrated.

What you need is use patterns. Examples. PURPOSES.

Think of this.

method drill: Makes holes in material that doesn't need hammering, like wood, metal or plastic. Check table@... for right tool for the material.
@params : tool, depth, direction
@return : hole

method hammer: Makes holes in material that needs hammering, specifically concrete. Use masonry bit for a tool.
@params : tool, depth, direction
@return : hole

Factory Screw: Binds things together. Requires hole of matching diameter in flexible materials like wood, threaded hole in metal, or a screw anchor of matching inner diameter in concrete.
@params : diameter, length.

Factory Screw_anchor: anchors screw to wall. Requires a hole of outer_diameter in concrete type material. Provides hole of inner_diameter in flexible type material. Should be installed using a hammer. Typical use is allowing installing screws in walls.
@params : inner_diameter, outer_diameter, length

Basing on such a documentation the user should be able to deduce the correct procedure for installing the screw for the picture frame. It contains purposes, actual practical requisites (as opposed to formal), hints on how to use given tools, when to use them, and if they have specific requisites in specific situations.

Even better is to provide rich examples, but these are to appear outside the direct function documentation. Nevertheless, besides writing what a function does, write its what for (purpose - why'd you ever need that result), actual requisites (not just a list of params it might take, but params it absolutely needs, typical usage patterns (hammer concrete, drill all the rest, a screw anchor needs to be driven by a hammer) and caveats (screw won't hold in raw concrete, needs screw anchor.)

Just telling what a function does is not helpful if I never know why it does it, and how to get it to do it right.

---

(0)

Login to post a comment!