Reference: Ability to overwrite @return

[gohai]

Hacking on the reference for processing-io I ran into two things that I couldn't get to work - and I think which might be limitations of the script that cranks out the reference. Posting them as separate issues for reference. Please feel free to close if this is known or very much the expected behavior. (And please tell me if there is a way to do it altogether!)

In Javadoc I sometimes use @return to describe the meaning of the return value. (E.g. that GPIO.digitalRead() returns either GPIO.HIGH or GPIO.LOW.) However the generated reference always just specifies the return type, which is perhaps not in all cases intuitive. I tried overwriting where it mattered in the XML files (setting <returns></returns>, which I found in the video library's files), but this didn't have an influence on the output either.

[scotthmurray]

@gohai Thanks for this. Our dream is to be able to rewrite the reference generator scripts to be able to accommodate scenarios like this. Yet, I don't think we have anyone with the skills and/or time to do this right now.

One complication is that, in general, we want to keep as much of the documentation directly in the source, so it also feeds into the JavaDoc. Currently, everything except the example snippets and longer descriptions are stored in the source. If we start adding exceptions, or additional info not in the source (i.e., in the XML files), we will have to do so carefully, to minimize potential confusion.

Somewhere I have a wishlist for the reference generator scripts. I will add this to the list, and then close this issue. I hope we could revisit this at some later date.

[gohai]

@alignedleft Thanks & understood!