Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reference: Ability to overwrite @syntax #397

Closed
gohai opened this issue Oct 19, 2015 · 2 comments · May be fixed by benfry/processing4#778
Closed

Reference: Ability to overwrite @syntax #397

gohai opened this issue Oct 19, 2015 · 2 comments · May be fixed by benfry/processing4#778
Assignees

Comments

@gohai
Copy link

gohai commented Oct 19, 2015

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 scotthmurray self-assigned this Oct 19, 2015
@scotthmurray
Copy link
Member

@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
Copy link
Author

gohai commented Oct 19, 2015

@alignedleft Thanks & understood!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants