<font size=2 face="sans-serif">I agree with points made by both Matt and
Radomir. </font>
<br>
<br><font size=2 face="sans-serif">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</font>
<br><font size=2 face="sans-serif">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</font>
<br><font size=2 face="sans-serif">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 </font>
<br><font size=2 face="sans-serif">so fellow team members could pick up
the code and quickly get caught up to speed and contribute by just reading
the code. </font>
<br>
<br><font size=2 face="sans-serif">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. </font>
<br><font size=2 face="sans-serif"><br>
<br>
Aaron D. Sahlin<br>
IBMUSM07(asahlin)<br>
Dept. X2WA<br>
Phone 507-253-7349 Tie 553-7349<br>
</font>
<br>
<br>
<br>
<br><font size=1 color=#5f5f5f face="sans-serif">From:
</font><font size=1 face="sans-serif">Matthew Farina <matt@mattfarina.com></font>
<br><font size=1 color=#5f5f5f face="sans-serif">To:
</font><font size=1 face="sans-serif">"OpenStack Development
Mailing List (not for usage questions)" <openstack-dev@lists.openstack.org></font>
<br><font size=1 color=#5f5f5f face="sans-serif">Date:
</font><font size=1 face="sans-serif">02/05/2015 11:29 AM</font>
<br><font size=1 color=#5f5f5f face="sans-serif">Subject:
</font><font size=1 face="sans-serif">Re: [openstack-dev]
[horizon] JavaScript docs?</font>
<br>
<hr noshade>
<br>
<br>
<br><font size=3>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.<br>
<br>
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.<br>
</font>
<br><font size=3>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.<br>
</font>
<br><font size=3>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.<br>
</font>
<br><font size=3>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.<br>
</font>
<br><font size=3>Just my 2 cents.</font>
<br>
<br>
<br><font size=3>On Thu, Feb 5, 2015 at 1:56 AM, Pavel Karikh <</font><a href=mailto:pkarikh@mirantis.com target=_blank><font size=3 color=blue><u>pkarikh@mirantis.com</u></font></a><font size=3>>
wrote:</font>
<br><font size=3 color=#40005f>On 02/05/2015 11:04 AM, Radomir Dopieralski wrote:</font><font size=3><br>
> </font><font size=2>Plus, the documentation generator that we
are using already, Sphinx,</font>
<br><font size=3>> </font><font size=2>supports JavaScript perfectly
fine, so I see no reason to add another tool.</font><font size=3><br>
<br>
I agree with Radomir, why we can't just use Sphinx? </font>
<br><font size=3><br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: </font><a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" target=_blank><font size=3 color=blue><u>OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</u></font></a><font size=3 color=blue><u><br>
</u></font><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target=_blank><font size=3 color=blue><u>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</u></font></a><font size=3><br>
</font>
<br><tt><font size=2>__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe<br>
</font></tt><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev"><tt><font size=2>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</font></tt></a><tt><font size=2><br>
</font></tt>
<br>