Open Stack

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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150205/c71c9802/attachment.html>