The doc pages for functions [1] [2] include these sections:
Returns
Usage
Arguments
Examples
See Also
Firstly, I was about to say “these pages need to include what the function returns”, because given the mismatch between the “Returns” heading formatting and the other headings’ formats: I didn’t actually spot it initially (even though it’s at the top!). So I think the “Returns” section heading should have its formatting promoted to be equal to the other headings. it’s equally important.
Secondly, I think simply stating the return type without explaining what / why that’s what’s returned is less helpful than it could be?
In the listAppend() example I link to, one can kind of glean it from the narrative, however it’d be more clear if the note was say something like “Returns the list with the element(s) appended”.
In the case of queryAddColumn(), all that’s said is it returns a number. What’s the number mean? that’s actually a serious question: I have no idea what a numeric return from this function might represent. Although with a bit of experimentation, it seems it’s the number of columns in the query after adding the column? RIght… yes… the CF docs say this “The number of the column that was added”. Cool, OK, now I know. But it’s an example where a description of the return value, as well as simply its type, might be useful?
If there’s no dissenting position on this, I’ll raise it as a Jira ticket.
NB: I tried to edit the docs entry to add a description, but it looks like that bit is derived from the source code, so is not editable. Also, I don’t want to simply go changing the general mise en scene (!) of the docs pages without initial consultation.
Cheers.
–
Adam
