<div dir="ltr"><div><div><div><div>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><br></div>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><br></div>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><br></div>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><br></div>Just my 2 cents.<br><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Feb 5, 2015 at 1:56 AM, Pavel Karikh <span dir="ltr"><<a href="mailto:pkarikh@mirantis.com" target="_blank">pkarikh@mirantis.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><font color="#500050">On 02/05/2015 11:04 AM, Radomir Dopieralski wrote:</font><span class=""><br>> <span style="font-size:13px">Plus, the documentation generator that we are using already, Sphinx,</span><br></span></div><div class="gmail_extra"><span class="">> <span style="font-size:13px">supports JavaScript perfectly fine, so I see no reason to add another tool.<br></span><br></span>I agree with Radomir, why we can't just use Sphinx? </div></div>
<br>__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br></div>