<div dir="ltr">JSDoc (ngdoc) is good thing. It allows to describe files, functions and it's parameters, constructors, classes in case of ES6.<div><br></div><div>The problem is it tends to diverge with reality. The code is being fixed and evolved, but comments are often not updated (who want to do much more work)? And JSDoc generated documentation loses the connection to reality. </div><div><br></div><div>Anton</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Feb 5, 2015 at 12:04 PM, Radomir Dopieralski <span dir="ltr"><<a href="mailto:openstack@sheep.art.pl" target="_blank">openstack@sheep.art.pl</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On 02/04/2015 06:06 PM, Thai Q Tran wrote:<br>
> As we're moving toward Angular, might make sense for us to adopt ngdoc<br>
> as well.<br>
<br>
</span>I don't think it makes much sense. We don't have any style guide for the<br>
JavaScript documentation simply because it's not needed. We don't really<br>
have any for Python either (although there might be a lot of<br>
python-specific stuff in what we have). We just have guidelines for<br>
documenting code. Any code. JavaScript, Python, even templates.<br>
<br>
Plus, the documentation generator that we are using already, Sphinx,<br>
supports JavaScript perfectly fine, so I see no reason to add another tool.<br>
<br>
I agree it would be nice to actually start using it for JavaScript code<br>
too, though.<br>
<span class="HOEnZb"><font color="#888888"><br>
--<br>
Radomir Dopieralski<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
<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>
</div></div></blockquote></div><br></div>