That is probably a bit clearer, but still not really clear.  Do we document the format of the return types from external service functions anywhere?  If so we should point them at that documentation.

Otherwise we should have the documentation in one place.  The rules are roughly:

If the function returns boolean, integers, real numbers then they are returned from the function.
If the function returns fixed length strings, then the memory for the result is allocated by the caller, and passed in via the __result parameter.
If the function returns a streamed dataset then you need to return an instance of a class (that implements the IRowStream interface).
If the function returns a linked dataset then you need to....  options for allocator or not.
If the function returns a linked row.....
Otherwise the function must allocate the memory using rtlMalloc, and assign to the __result parameter, and the length to the __lenResult parameter.
Also note __lenResult is the length of the string in characters (ascii or unicode) not the size in bytes.

I agree the documentation needs improving, but I suspect this needs clarifying and detailing in an email/jira first.