Verb forms in reference documentation

When you're writing reference documentation for a method, phrase the main method description in terms of what the method does (gets, lists, creates, searches), rather than what the developer would use it to do (get, list, create, search).

It's a subtle distinction that manifests mostly in whether the initial verb in the description has an -s at the end or not.

Examples

Not recommended: tasks.insert: Create a new task on the specified task list.

Recommended: tasks.insert: Creates a new task on the specified task list.

In a specification that's aimed at implementors of an API, it may make more sense to use the verb form without the -s; in that context, you're telling the reader what their implementation of the method should do ("create a new task"), whereas in reference docs aimed at developers, you're telling them what the existing method does ("creates a new task").