: How can I express this more clearly or concisely? I'm documenting a block of computer code and would like to make it clear and concise. I'm describing a function that populates a field on

Vote Up Vote Down

Given your comment to Monica, it seems to me that your original description goes way beyond what the function actually does. In particular, the function does not itself display the seller id, but instead returns it to some other code that displays it. The f_get_vend_code() function itself does not interact with either the form or the field, so there's no need to mention them.

If that's true, describe only what the function does: "This function returns the vendor code for the nut identified by NUT_ID."

Also: The name of the function and its parameter seem almost sufficient documentation in and of themselves. Could you improve those names so as to make the documentation unnecessary? At least spell out "vendor" instead of unnecessarily abbreviating it as "vend". If you do that, what's left for the documentation to convey?

(0)

Vote Up Vote Down

Try

For a given NUT_ID, this function provides the WINGNUT_SELLER_CODE that fills the 'Vendor' field on the 'THREADED_NUTS' screen.

Your original comment is

This function returns the WINGNUT_SELLER_CODE that appears in the 'Vendor' field
on the 'THREADED_NUTS' screen for a given NUT_ID.

(0)

Vote Up Vote Down

Edited based on comments:

Given the following function declaration:

f_get_vend_code(v_nut_id varchar2) return varchar2;

I would write the description as follows:

This function takes a nut ID (NUT_ID) and returns the vendor's seller code (WINGNUT_SELLER_CODE) for this form. If NUT_ID is not set (blah blah blah). If the function cannot find a valid seller ID it (does something).

Note: I'm using Java idioms because those are the ones I'm familiar with. I'm assuming that "takes (a parameter)" and "returns" are meaningful for your audience too; you should verify that by reading other API documentation for this language. I am also assuming that the values you originally used, e.g. NUT_ID, are meaningful even though they don't appear in the signature; if that's not the case then I would omit them in the description.

Also note that I went beyond your original question to cover invalid parameters and error conditions. Good API documentation goes beyond what they can get from just reading the signature and tells them what they wouldn't be able to figure out otherwise.

(0)

Vote Up Vote Down

Maybe break it into two sentences?

When you send this function a NUT_ID, it returns a WINGNUT_SELLER_CODE. This code is from the'THREADED_NUTS' screen in the 'Vendor' field.

I almost always use "that". (Every copy editor I've ever encountered seems determined to eradicate all uses of "which".

(0)