Enhance the "returns" section for function reference docs

The doc pages for functions [1] [2] include these sections:

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.



I agree. How about something like this (the return type has been put into the signature):

You should be able to edit the function descriptions though. I think that’s a sensible place for having detailed return information where necessary.

Yeah, Dom, this is better than what’s there. However I still think there should be a section @ the same “level” as Usage / Arguments for Returns, too.

Your change here is - to the return type - what the argument list is in the rest of the method signature is to the arguments. So in a way you’ve fixed the function signature formatting here, rather than dealing with the omission of the description of return type. Does that make sense?

The ColdFusion docs (eg: listAppend()) demonstrate what I mean. They have a clear section for the function’s inputs (Parameters) and for its outputs (Returns).

MDN do it similarly: Array.push(): both Paramters and Returns sections.

This is in addition to the function signature / syntax description.

I think what you demonstrate is a positive move though, as well.

Cheers mate.


That makes sense. I was weary of adding too much structured data, but it is definitely beneficial.


Cheers Dom.


1 Like