I am the one working on adding comments prototype. My focus is on commenting the internals of functions, but I did decide to use PDoc to document each function. You can see my progress here: http://dev.rubyonrails.org/ticket/11368. I invite others to update the diff's I've already submitted to clarify or rewrite some of the comments I've already done.
I decided to use PDoc because it is concise and is the most easily readable to a casual browser of the source code. My idea is to update the rake function included in the source to strip the comments by default but optionally preserve them. I'm thinking that others who want code completion from visual studio or a javadoc reader should take one of two paths: (a) write a script to convert the PDoc comments into another format (b) port comments into the source code directly from prototypejs.org/api/ Tobie, is your idea to use a PDoc version of the source code to generate the content of prototypejs.org/api/? If not, someone may be interested in writing a script that takes the contents of prototypejs.org/api/ and adds them into the source programmatically--attacking the problem from the opposite angle, if you will. Right now I'm describing the functions as if you have the source in front of you, so instead of the prototypejs.org/api/ approach of "here is the use of this function" my approach is "the function processes inputs this way and gives outputs this way." My feeling is that the comments can't be everything to everyone, but perhaps we can automate it to generate different versions. Regardless, as I mentioned my focus is commenting on the internals of functions. I think comments inside of functions will be compatible with any official decisions on generating documentation or supporting code completion. Any thoughts are welcomed. Thanks, Ken Snyder Tobie Langel wrote: > Hi, > > PDoc is currently in alpha. A beta release should be announced in the > upcoming weeks. > > Best, > > Tobie --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Ruby on Rails: Spinoffs" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/rubyonrails-spinoffs?hl=en -~----------~----~----~----~------~----~------~--~---
