Open Stack

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 <matt at mattfarina.com>
To:     "OpenStack Development Mailing List (not for usage questions)" 
<openstack-dev at lists.openstack.org>
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 <pkarikh at mirantis.com> 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: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150205/d6782609/attachment.html>