<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On 10 March 2016 at 06:49, Michael Krotscheck <span dir="ltr"><<a href="mailto:krotscheck@gmail.com" target="_blank">krotscheck@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>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.</div></div></blockquote><div><br></div><div>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.</div><div><br></div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>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.</div></div></blockquote><div><br></div><div>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.</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>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.</div></div></blockquote><div><br></div><div>Yep!</div><div><br></div><div><br></div><div>     Richard</div><div><br></div></div></div></div>