Open Stack

On 10 March 2016 at 06:49, Michael Krotscheck <krotscheck at gmail.com> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160310/ccf1baa6/attachment.html>