Reference: Ability to overwrite @syntax

[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!)

As far as I can tell, a method's syntax is always simply displayed as .method(params) in the generated documentation - without an indication if the method is perhaps static, and thus can be called without instantiating a new object.

The Hardware I/O library consists partially of static methods, like digitalRead(), which are done this way in order to stay close to the Arduino API, and partially of "proper" classes, like for I2C and SPI. I am was thinking that it could be helpful to specify the syntax of static methods by prefixing it by the class name. So instead of digitalRead() being .digitalRead(pin) it would be GPIO.digitalRead(pin), since you wouldn't use this method in any other context really.

I tried overwriting the syntax in the XML file (setting <syntax></syntax>), but this didn't seem to have had an effect on the output.

[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!