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.


From: Michael Krotscheck <krotsch...@gmail.com<mailto:krotsch...@gmail.com>>
Reply-To: OpenStack List 
Date: Wednesday, March 9, 2016 at 12:49 PM
To: OpenStack List 
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.


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.


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).


[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)

OpenStack Development Mailing List (not for usage questions)
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe

Reply via email to