Use the implementation and a few observable checks as the basis for the comment. A fluent description cannot establish behavior absent from the supplied code.
Read the returned values before writing the comment
This original teaching function accepts an array of ordinary record objects. It returns the same records in a new array:
function copyRecords(records) {
if (!Array.isArray(records)) {
throw new TypeError("records must be an array");
}
return records.slice();
}
The function checks that the argument is an array. It does not validate the elements' fields, clone their properties or freeze them. For the declared plain-record use case, the returned array is distinct while each record object remains shared.
A suitable comment is:
/**
* Return a shallow copy of the records array.
* The returned array is new; its record objects remain shared.
* Adding or removing entries in the result does not change the input
* array, but changing a shared record's properties affects that record.
* @param {Object[]} records - Ordinary record objects; fields are not validated.
* @returns {Object[]} A new array containing the same record references.
* @throws {TypeError} If records is not an array.
*/
The comment describes the intended plain-record domain. It does not turn Object[] into a runtime check. JSDoc's official parameter, return-value and error references, checked October 24, 2026, define those documentation tags.
Check identity and mutation separately
Run this after defining the exact function above in a JavaScript console:
const input = [{ label: "draft" }];
const output = copyRecords(input);
console.assert(output !== input, "new array expected");
console.assert(output[0] === input[0], "shared record expected");
output.push({ label: "extra" });
console.assert(input.length === 1, "input array length unchanged");
output[0].label = "review";
console.assert(input[0].label === "review", "shared object changed");
let error;
try { copyRecords(null); } catch (caught) { error = caught; }
console.assert(error instanceof TypeError, "TypeError expected");
These cases answer different questions. The array-identity check establishes a new outer container. The record-identity and property check establish sharing. The length check shows that pushing a new entry does not append it to the input array. The invalid-input check exercises the explicit guard.
Ask for a comment without changing the function
Write a JSDoc comment for this exact function.
Complete function and relevant called helpers: [PASTE]
Intended input domain and caller expectations: [ENTER]
Existing execution results and edge cases: [PASTE, OR NONE]
Describe accepted input, return value and identity, mutation effects,
and errors supported by the implementation. Separate static type
annotations from actual runtime validation. Do not add deep-copy,
immutability, performance or compatibility promises without evidence.
Do not refactor the function. Return the comment and a short list of
checks that could disprove it. Mark missing behavior as unresolved.
The task-and-context structure follows OpenAI's prompting guidance. Ask for a narrow correction if the draft says independent objects: replace that claim with shared references, then compare the whole comment with the code again.
For repository setup commands and project-wide instructions, the README-generation guide addresses a different documentation layer. Keep this function comment immediately above its implementation and retain the identity, mutation and invalid-input checks with its tests. If the implementation later changes to clone records, update both the comment and the assertions in that same review.