Writing API Documentation

API endpoint documentation must include: HTTP method and path, what it returns, error responses with conditions, auth requirements, and rate limits. Option B hits all five. Option A omits the HTTP method, the path format, error handling, auth, and rate limits. Option C uses informal language ("pretty straightforward") and makes no technical claim. Option D is so vague it provides no value — "various user-related operations" could describe any endpoint.

API documentation uses present simple throughout — it describes the permanent, designed behaviour of the API, not something that happens in the future or is happening right now. Accepts, is, returns — all present simple. For the conditional clause, "if omitted" is a reduced passive clause (short for "if [it is] omitted") — this is grammatical and very common in technical documentation because it is concise. "If it is omitted" (option C) is equally correct but slightly more verbose. "Will return" (option B) sounds like a prediction rather than a specification — present simple is the correct register for documented behaviour.

Deprecation notices require: the deprecated item, date deprecated, the replacement, removal date, and a migration path. Option B includes all five. Option A uses informal language ("old") and doesn't specify what the new endpoint is or when the old one disappears. Option C uses hedged language ("might not work") — deprecated APIs will be removed on a known date, not "might" stop working. Option D gives no dates, no replacement path, and no migration guide.

Code example comments in API docs should tell readers what the example demonstrates, what inputs are involved, and what to expect from the response. Option B: names the operation (create a user), names the key fields being set (email, name, role), and describes the response (201 status, created object, generated ID). This lets a developer read the comment and know exactly what they're looking at without running the code. Option A says nothing. Options C and D restate what the HTTP method already tells you — they add no new information.

Technical specifications use present simple throughout: controls, returned, defaults, is. These describe permanent, designed behaviour. Returned (past participle) acts as an adjective modifying "results" — "results returned per page" is a reduced relative clause ("results that are returned"). Defaults (present simple) for a designed fallback value. Not provided (past participle) in a reduced conditional ("if not provided" = "if it is not provided"). Is for a factual statement about the maximum. Option C uses "will be" for the maximum, which implies a future change — present simple is correct for a current, stable constraint.