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

Michael Krotscheck krotscheck at gmail.com
Thu Mar 10 17:55:48 UTC 2016


On Wed, Mar 9, 2016 at 4:15 PM Richard Jones <r1chardj0n3s at gmail.com> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160310/0ca98639/attachment.html>


More information about the OpenStack-dev mailing list