Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-09 Thread Radomir Dopieralski
On 02/05/2015 07:26 PM, Michael Krotscheck wrote: On Thu Feb 05 2015 at 12:07:01 AM Radomir Dopieralski openst...@sheep.art.pl mailto:openst...@sheep.art.pl wrote: Plus, the documentation generator that we are using already, Sphinx, supports JavaScript perfectly fine, so I see no

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-09 Thread Radomir Dopieralski
On 02/05/2015 06:20 PM, Matthew Farina wrote: 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

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-05 Thread Radomir Dopieralski
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

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-05 Thread Anton Zemlyanov
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

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-05 Thread Pavel Karikh
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?

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-05 Thread Aaron D Sahlin
. Aaron D. Sahlin IBMUSM07(asahlin) Dept. X2WA Phone 507-253-7349 Tie 553-7349 From: Matthew Farina m...@mattfarina.com To: OpenStack Development Mailing List (not for usage questions) openstack-dev@lists.openstack.org Date: 02/05/2015 11:29 AM Subject:Re: [openstack-dev] [horizon

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-05 Thread Matthew Farina
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

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-05 Thread Jeremy Stanley
On 2015-02-05 09:20:35 -0800 (-0800), Matthew Farina wrote: [...] 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. [...] Particularly since Sphinx collects the method/class/function docstrings

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-05 Thread Radomir Dopieralski
On 02/05/2015 10:27 AM, Anton Zemlyanov wrote: JSDoc (ngdoc) is good thing. It allows to describe files, functions and it's parameters, constructors, classes in case of ES6. As does Sphinx. The problem is it tends to diverge with reality. The code is being fixed and evolved, but comments are

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-05 Thread Matthew Farina
Ah, I had forgotten about the python module documentation. Sorry about that and thanks for pointing it out. Can we have that system parse and use JSDoc? I'd like it to be useful to both JS devs and the doc generation toolchain. On Thu, Feb 5, 2015 at 9:42 AM, Jeremy Stanley fu...@yuggoth.org

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-05 Thread Michael Krotscheck
On Thu Feb 05 2015 at 12:07:01 AM Radomir Dopieralski openst...@sheep.art.pl wrote: Plus, the documentation generator that we are using already, Sphinx, supports JavaScript perfectly fine, so I see no reason to add another tool. Try to empathize with us a little here. What you're asking is

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-05 Thread Jeremy Stanley
On 2015-02-05 10:19:39 -0800 (-0800), Matthew Farina wrote: [...] Can we have that system parse and use JSDoc? I'd like it to be useful to both JS devs and the doc generation toolchain. A quick Web search turned up https://github.com/debrouwere/jsdoc-for-sphinx and

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-04 Thread Michael Krotscheck
) openstack-dev@lists.openstack.org From: Matthew Farina m...@mattfarina.com Date: 02/04/2015 05:42AM Subject: [openstack-dev] [horizon] JavaScript docs? In python we have a style to document methods, classes, and so forth. But, I don't see any guidance on how JavaScript should be documented

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-04 Thread Thai Q Tran
As we're moving toward Angular, might make sense for us to adopt ngdoc as well.-Matthew Farina m...@mattfarina.com wrote: -To: "OpenStack Development Mailing List (not for usage questions)" openstack-dev@lists.openstack.orgFrom: Matthew Farina m...@mattfarina.comDate: 02/04/2015

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-04 Thread Monty Taylor
: - To: OpenStack Development Mailing List (not for usage questions) openstack-dev@lists.openstack.org From: Matthew Farina m...@mattfarina.com Date: 02/04/2015 05:42AM Subject: [openstack-dev] [horizon] JavaScript docs? In python we have a style to document methods, classes, and so forth

Re: [openstack-dev] [horizon] JavaScript docs?

2015-02-04 Thread Eric Helms
, February 4, 2015 4:00:17 PM Subject: Re: [openstack-dev] [horizon] JavaScript docs? On 02/04/2015 12:48 PM, Michael Krotscheck wrote: I agree. StoryBoard's storyboard-webclient project has a lot of existing code already that's pretty well documented, but without knowing what

[openstack-dev] [horizon] JavaScript docs?

2015-02-04 Thread Matthew Farina
In python we have a style to document methods, classes, and so forth. But, I don't see any guidance on how JavaScript should be documented. I was looking for something like jsdoc or ngdoc (an extension of jsdoc). Is there any guidance on how JavaScript should be documented? For anyone who doesn't