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

Richard Jones r1chardj0n3s at gmail.com
Wed Mar 9 02:25:40 UTC 2016

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


[1] http://governance.openstack.org/reference/cti/javascript-cti.html
[2] https://review.openstack.org/#/c/290235/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160309/c44d406e/attachment.html>

More information about the OpenStack-dev mailing list