<div dir="ltr"><br><br><div class="gmail_quote"><div dir="ltr">On Wed, Mar 9, 2016 at 4:15 PM Richard Jones <<a href="mailto:r1chardj0n3s@gmail.com">r1chardj0n3s@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><br></div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><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></div></div></blockquote><div><br></div><div>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.</div><div><br></div><div>In the meantime, they do provide a benefit - for one, I know that Matt Borland is working on digging into those warnings.</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 class="gmail_extra"><div class="gmail_quote"><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.</div></div></div></div></blockquote><div><br></div><div>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?</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 class="gmail_extra"><div class="gmail_quote"><div>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).</div></div></div></div></blockquote><div><br></div><div>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.</div><div><br></div><div>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.</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 class="gmail_extra"><div class="gmail_quote"><div>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.</div></div></div></div></blockquote><div><br></div><div>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?<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 class="gmail_extra"><div class="gmail_quote"><div> 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></div></div></blockquote><div><br></div><div>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.</div><div><br></div><div>Michael </div></div></div>