I agree with points made by both Matt and Radomir. We have guidelines for documenting code. Any code. (* I need to go see what our guidelines actually say) But the goal is to have comments that are useful and make the code easier to understand, follow and use. Comments should focus on "what and why" vs "how". Some files are trivial, but I always appreciated having file level comments describing the purpose of this file. Then having method level comments for non-trivial methods, and so forth down to code blocks. This is how projects I have worked on in the past have commented so fellow team members could pick up the code and quickly get caught up to speed and contribute by just reading the code.
Now that I am done rambling on comment content.... As far as structure it would be nice to follow convention and use JSDoc or ngDoc for JavaScript files. Aaron D. Sahlin IBMUSM07(asahlin) Dept. X2WA Phone 507-253-7349 Tie 553-7349 From: Matthew Farina <[email protected]> To: "OpenStack Development Mailing List (not for usage questions)" <[email protected]> Date: 02/05/2015 11:29 AM Subject: Re: [openstack-dev] [horizon] JavaScript docs? I'd like to step back for a moment as to the purpose of different kinds of documentation. Sphinx is great and it provides some forms of documentation. But, why do we document methods, classes, or functions in python? Should we drop that and rely on Sphinx? I don't think anyone would argue for that. Some documentation has a different purpose. For example, text editors and IDEs can introspect comments and help as we're writing the code. Or, say you have a bit of bit of code like the reusable wizard being written JavaScript. If someone is going to use it there should be a code comment about it. Just like you'd have for the tables class in Python because people are going to use it. JavaScript is a programming language just as much as Python is. If we should have comments in Python we should have comments in JavaScript. It's no different. JSDoc is the common format for JavaScript. It will help with text editors and IDEs. If we are going to move into an API docs site (which we don't have now) using ngDoc would be helpful. I think documenting in a useful manner is a different piece of scope from using that documentation to generate a site. Ideally, we would document JavaScript in a useful manner no matter if we are creating html docs from it or not. To document in a useful manner we should likely use JSDoc (or ngDoc) for the useful tools rather than do it our own way. We should use the wheel everyone else is using rather than do it our own way. Just my 2 cents. On Thu, Feb 5, 2015 at 1:56 AM, Pavel Karikh <[email protected]> wrote: On 02/05/2015 11:04 AM, Radomir Dopieralski wrote: > Plus, the documentation generator that we are using already, Sphinx, > supports JavaScript perfectly fine, so I see no reason to add another tool. I agree with Radomir, why we can't just use Sphinx? __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
