Post History

Source: https://writers.stackexchange.com/a/3849
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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.

Original score: 4