Open Stack

JSDoc (ngdoc) is good thing. It allows to describe files, functions and
it's parameters, constructors, classes in case of ES6.

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.

Anton

On Thu, Feb 5, 2015 at 12:04 PM, Radomir Dopieralski <openstack at sheep.art.pl
> wrote:

> On 02/04/2015 06:06 PM, Thai Q Tran wrote:
> > As we're moving toward Angular, might make sense for us to adopt ngdoc
> > as well.
>
> I don't think it makes much sense. We don't have any style guide for the
> JavaScript documentation simply because it's not needed. We don't really
> have any for Python either (although there might be a lot of
> python-specific stuff in what we have). We just have guidelines for
> documenting code. Any code. JavaScript, Python, even templates.
>
> 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 it would be nice to actually start using it for JavaScript code
> too, though.
>
> --
> Radomir Dopieralski
>
>
> __________________________________________________________________________
> 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/28c49055/attachment.html>