Re: [openstack-dev] [Horizon] Javascript linting and documentation

2016-03-19 Thread Richard Jones 
On 11 March 2016 at 04:37, Michael Krotscheck  wrote:

> On Wed, Mar 9, 2016 at 12:45 PM Tripp, Travis S 
> wrote:
>
>> The problem is that the warnings are so great that is really hard to read.
>>
>
> If all the warnings were fixed - I know Matt Borland's working on that -
> would we be having this conversation?
>

My position was that I didn't want Matt to waste his valuable time editing
a bunch of JSDoc when we might end up having to go through and re-edit it
to some other form. We've busy enough with Mitaka release issues during
these weeks without needing to be bothered by fixing ignorable some jsdoc
lint warnings (and they are ignorable - nothing currently cares about the
syntax of our Javascript comments *except* the linter).


 Richard
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Horizon] Javascript linting and documentation

2016-03-10 Thread Michael Krotscheck 
On Wed, Mar 9, 2016 at 4:15 PM Richard Jones  wrote:

>
> We already have a "lintq" npm task that does this, which most of us use.
> The problem is that we then ignore all the legitimate code linting warnings.
>

I think we both agree that some form of jsdoc linting is useful, yes? You'd
prefer for it to be in the doc builder, while I'm ambivalent about where
those checks happen. How about this: Let's keep the checks in there, and
once a replacement is in place, we can turn it off.

In the meantime, they do provide a benefit - for one, I know that Matt
Borland is working on digging into those warnings.


> My perspective on this is if the documentation builder can produce
> documentation that is useful then it's enforcing exactly enough checks on
> the input.
>

It sounds like we don't actually know what this documentation builder is
going to enforce. In fact, it may be more strict and/or less configurable
than eslint. I'm not comfortable turning off a rule if we don't know what
kind of a future we'll get; could you investigate and report back with your
findings?


> For example, the jsdoc linter currently forces us to write @returns
> statements in our docs for angular methods that have no return value, and
> never will (i.e. module.config()) or is otherwise not exposed to developers
> and not interesting (i.e. the return from service or controller
> construction).
>

Given javascript's flexible return types, many IDE's look to the jsdoc to
guess at what the returned type for a method is. This drives things like
code hinting, sanity checks, and tab completion. Explicitly declaring the
return type, even if it's {void}, has a concrete benefit.

And yes, I find it annoying too, but I put up with it for the beauty of
Command-Space-Oh-That's-What-I-Can-Do-Here.


> I mentioned this in passing in the meeting, but most of our JS
> documentation has been written to ngdoc syntax, and that's potentially a
> good thing since it provides much greater hinting to the doc generators
> about how to present and organise the output, but also influences things
> like @returns usefulness.
>

I remember you saying that ngdoc doesn't actually work, so I'm a bit
confused as to why we're writing documentation to that standard. Could you
clarify?


> We just have to find the right tool (or, more likely, create, since I've
> been looking for a while and haven't found a suitable tool) that uses the
> information we're coding into our comments.
>

Awesome. So once this tool is completed, let's come back to this
conversation! I don't think we can continue without really knowing what the
tradeoffs will be.

Michael
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Horizon] Javascript linting and documentation

2016-03-10 Thread Michael Krotscheck 
On Wed, Mar 9, 2016 at 12:45 PM Tripp, Travis S 
wrote:

> The problem is that the warnings are so great that is really hard to read.
>

If all the warnings were fixed - I know Matt Borland's working on that -
would we be having this conversation?

Michael
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Horizon] Javascript linting and documentation

2016-03-09 Thread Richard Jones 
On 10 March 2016 at 06:49, Michael Krotscheck  wrote:

> I guess I don't see what problems is being solved by turning the rule off,
> and I also don't see the harm in having more check. It does generate a lot
> of warnings, but invoking `npm run lint -- --quiet` gets rid of those.
>

We already have a "lintq" npm task that does this, which most of us use.
The problem is that we then ignore all the legitimate code linting warnings.


Also, from my experience, sphinx-based doc builds are notoriously
> permissive about bad formatting. Eslint's stricter jsdoc checks would add
> an additional safety net.
>

My perspective on this is if the documentation builder can produce
documentation that is useful then it's enforcing exactly enough checks on
the input. For example, the jsdoc linter currently forces us to write
@returns statements in our docs for angular methods that have no return
value, and never will (i.e. module.config()) or is otherwise not exposed to
developers and not interesting (i.e. the return from service or controller
construction). I mentioned this in passing in the meeting, but most of our
JS documentation has been written to ngdoc syntax, and that's potentially a
good thing since it provides much greater hinting to the doc generators
about how to present and organise the output, but also influences things
like @returns usefulness. We just have to find the right tool (or, more
likely, create, since I've been looking for a while and haven't found a
suitable tool) that uses the information we're coding into our comments.



> However, if you're working on this with the docs team, then the result
> should be applicable to the entirety of openstack - meaning that once your
> work is complete, it may make sense to turn the rule off globally.
>

Yep!


 Richard
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Horizon] Javascript linting and documentation

2016-03-09 Thread Tripp, Travis S 
Hi Michael,

The problem is that the warnings are so great that is really hard to read.

What if we amended the recently added lintq to do some inline filtering of the 
doc warnings?  This is just a bandaid of course.

I also am opposed to any major linting changes until Mitaka closes. They cause 
too many merge conflicts when the fix goes in, making the real bugs harder to 
get through.

-Travis

From: Michael Krotscheck <krotsch...@gmail.com<mailto:krotsch...@gmail.com>>
Reply-To: OpenStack List 
<openstack-dev@lists.openstack.org<mailto:openstack-dev@lists.openstack.org>>
Date: Wednesday, March 9, 2016 at 12:49 PM
To: OpenStack List 
<openstack-dev@lists.openstack.org<mailto:openstack-dev@lists.openstack.org>>
Subject: Re: [openstack-dev] [Horizon] Javascript linting and documentation

+1 to what Rob said.

I guess I don't see what problems is being solved by turning the rule off, and 
I also don't see the harm in having more check. It does generate a lot of 
warnings, but invoking `npm run lint -- --quiet` gets rid of those. Also, from 
my experience, sphinx-based doc builds are notoriously permissive about bad 
formatting. Eslint's stricter jsdoc checks would add an additional safety net.

However, if you're working on this with the docs team, then the result should 
be applicable to the entirety of openstack - meaning that once your work is 
complete, it may make sense to turn the rule off globally.

Michael

On Wed, Mar 9, 2016 at 11:14 AM Rob Cresswell (rcresswe) 
<rcres...@cisco.com<mailto:rcres...@cisco.com>> wrote:
If possible, I’d really prefer we left linting work to Newton. It’ll be good to 
get it to a more usable state again, but we ought to be focusing on thoroughly 
checking the new Launch Instance for bugs and edge usage cases, as well as the 
outstanding bugs and blueprints targeted at RC1 
(https://launchpad.net/horizon/+milestone/mitaka-rc1). This is a great 
opportunity to prove that the Angular rewrites are fully capable of providing 
an improved experience, and we should be capitalising on that.

Rob


On 9 Mar 2016, at 02:25, Richard Jones 
<r1chardj0...@gmail.com<mailto:r1chardj0...@gmail.com>> wrote:

Hey all,

I started looking into fixing the wall of "npm run lint" warnings today and 
quickly noticed that about 85% of the "linting" warnings were about jsdoc. We 
have significant issues around jsdoc anyway and we're supposed to be using 
Sphinx anyway[1].

Some Horizon folks will know that I've been investigating generating 
publishable documentation for our Javascript code for some time. Most of the 
tools either don't work (dgeni) or produce pretty unusable output for a project 
our size (jsdoc and grunt-ngdocs). I am about to investigate Sphinx in 
collaboration with the docs team.

Regardless, I believe that the documentation generation should generate errors 
about that documentation, not the code linter. Once we actually get a 
documentation generator going. Until then, we don't even know what syntax the 
documentation should follow.

I've proposed a change which just turns jsdoc "linting" off[2]. At the moment, 
it is less than useful (the noise drowns out any other, legitimate linting).


 Richard


[1] http://governance.openstack.org/reference/cti/javascript-cti.html
[2] https://review.openstack.org/#/c/290235/

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 
openstack-dev-requ...@lists.openstack.org<mailto:openstack-dev-requ...@lists.openstack.org>?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 
openstack-dev-requ...@lists.openstack.org?subject:unsubscribe<http://openstack-dev-requ...@lists.openstack.org?subject:unsubscribe>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Horizon] Javascript linting and documentation

2016-03-09 Thread Michael Krotscheck 
+1 to what Rob said.

I guess I don't see what problems is being solved by turning the rule off,
and I also don't see the harm in having more check. It does generate a lot
of warnings, but invoking `npm run lint -- --quiet` gets rid of those.
Also, from my experience, sphinx-based doc builds are notoriously
permissive about bad formatting. Eslint's stricter jsdoc checks would add
an additional safety net.

However, if you're working on this with the docs team, then the result
should be applicable to the entirety of openstack - meaning that once your
work is complete, it may make sense to turn the rule off globally.

Michael

On Wed, Mar 9, 2016 at 11:14 AM Rob Cresswell (rcresswe) 
wrote:

> If possible, I’d really prefer we left linting work to Newton. It’ll be
> good to get it to a more usable state again, but we ought to be focusing on
> thoroughly checking the new Launch Instance for bugs and edge usage cases,
> as well as the outstanding bugs and blueprints targeted at RC1 (
> https://launchpad.net/horizon/+milestone/mitaka-rc1). This is a great
> opportunity to prove that the Angular rewrites are fully capable of
> providing an improved experience, and we should be capitalising on that.
>
> Rob
>
>
> On 9 Mar 2016, at 02:25, Richard Jones  wrote:
>
> Hey all,
>
> I started looking into fixing the wall of "npm run lint" warnings today
> and quickly noticed that about 85% of the "linting" warnings were about
> jsdoc. We have significant issues around jsdoc anyway and we're supposed to
> be using Sphinx anyway[1].
>
> Some Horizon folks will know that I've been investigating generating
> publishable documentation for our Javascript code for some time. Most of
> the tools either don't work (dgeni) or produce pretty unusable output for a
> project our size (jsdoc and grunt-ngdocs). I am about to investigate Sphinx
> in collaboration with the docs team.
>
> Regardless, I believe that the documentation generation should generate
> errors about that documentation, not the code linter. Once we actually get
> a documentation generator going. Until then, we don't even know what syntax
> the documentation should follow.
>
> I've proposed a change which just turns jsdoc "linting" off[2]. At the
> moment, it is less than useful (the noise drowns out any other, legitimate
> linting).
>
>
>  Richard
>
>
> [1] http://governance.openstack.org/reference/cti/javascript-cti.html
> [2] https://review.openstack.org/#/c/290235/
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Horizon] Javascript linting and documentation

2016-03-09 Thread Rob Cresswell (rcresswe) 
If possible, I’d really prefer we left linting work to Newton. It’ll be good to 
get it to a more usable state again, but we ought to be focusing on thoroughly 
checking the new Launch Instance for bugs and edge usage cases, as well as the 
outstanding bugs and blueprints targeted at RC1 
(https://launchpad.net/horizon/+milestone/mitaka-rc1). This is a great 
opportunity to prove that the Angular rewrites are fully capable of providing 
an improved experience, and we should be capitalising on that.

Rob


On 9 Mar 2016, at 02:25, Richard Jones 
> wrote:

Hey all,

I started looking into fixing the wall of "npm run lint" warnings today and 
quickly noticed that about 85% of the "linting" warnings were about jsdoc. We 
have significant issues around jsdoc anyway and we're supposed to be using 
Sphinx anyway[1].

Some Horizon folks will know that I've been investigating generating 
publishable documentation for our Javascript code for some time. Most of the 
tools either don't work (dgeni) or produce pretty unusable output for a project 
our size (jsdoc and grunt-ngdocs). I am about to investigate Sphinx in 
collaboration with the docs team.

Regardless, I believe that the documentation generation should generate errors 
about that documentation, not the code linter. Once we actually get a 
documentation generator going. Until then, we don't even know what syntax the 
documentation should follow.

I've proposed a change which just turns jsdoc "linting" off[2]. At the moment, 
it is less than useful (the noise drowns out any other, legitimate linting).


 Richard


[1] http://governance.openstack.org/reference/cti/javascript-cti.html
[2] https://review.openstack.org/#/c/290235/

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 
openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev