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.
Recommended: tasks.insert: Creates a new
task on the specified task list.
Not recommended: tasks.insert: Create a
new task on the specified task list.
For more information and examples, see the
Google Cloud API design guide.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-10-15 UTC.
[null,null,["Last updated 2024-10-15 UTC."],[[["When writing documentation for methods, focus on what the method accomplishes (e.g., \"creates\") rather than the developer's action (e.g., \"create\")."],["This subtle difference is mainly reflected in whether the initial verb in the description is singular or plural, with the singular form being preferred."],["Refer to Google Cloud API design guide for further details and illustrations."]]],["Method descriptions in reference documentation should focus on the method's actions, using verbs with an \"-s\" ending. This means describing what the method *does* (e.g., *creates*, *lists*) rather than what the developer *would do* with it (e.g., *create*, *list*). For example, \"Creates a new task\" is preferred over \"Create a new task.\" This convention enhances clarity and consistency in API documentation. Refer to the Google Cloud API design guide for further details.\n"]]