Closed
Description
There is a spurious entry in the API docs: http://apidocs.strongloop.com/loopback/#if
The code comment seems like it should not be picked up the strong-docs, but it's incorrectly picking it up. Perhaps we can just remove the entire comment block:
/*!
* Expose path to the default favicon file
*
* ***only in node***
*/
Any objections @superkhau @bajtos or anyone else?
Activity
superkhau commentedon Jul 22, 2016
Yeah, it should be removed from the API docs.
bajtos commentedon Jul 25, 2016
The comment should stay in the source file, I think it's useful. However, the comment should use such format so that strong-docs does not pick it as a jsdoc comment.
@hacksparrow what's the right way for writing a comment that should be ignored by jsdoc? I thought that
/*!should be ignored by jsdoc parser used by strong-docs, at least it used to be that way. I am proposing to make our jsdoc parser more strict and recognize only comments starting with/**or///. Thoughts?cc @ritch
crandmck commentedon Jul 25, 2016
I thought so, too. Not sure why it's picking up this block. Could be a bug in strong-docs?
superkhau commentedon Jul 25, 2016
Exactly this. Can we just use normal
//?crandmck commentedon Jul 25, 2016
That would be a good workaround (and will work AFAIK), but I agree with @bajtos that we should fix strong-docs to properly ignore "non-doc" comment lines/blocks.
Update loopback.js
crandmck commentedon Jul 26, 2016
I went ahead and fixed this with the "workaround" with 1b55d35
But I'd like to see if we can address this bug in strong-docs @hacksparrow
IAC, I'll wait for npm republish to close this.
hacksparrow commentedon Aug 1, 2016
@crandmck that's just the way
dox(whichsdocsuses) works. Do not use the/* */comments if not intended as a JSdoc block.crandmck commentedon Aug 1, 2016
Wait, doc comments are
NOT
/*in the leading comment line.Anyway, the original comment here started with
/*!anddoxspecifically states that/*!comments are ignored; see https://www.npmjs.com/package/dox#ignore.hacksparrow commentedon Aug 1, 2016
I was looking at the updated code, let me review with the previous code.
hacksparrow commentedon Aug 1, 2016
is being ignored on my local machine. However, I am using the latest unpublished version of
sdocs.If strongloop/strong-docs#74 is merged, you can use the version I am using.
crandmck commentedon Aug 2, 2016
I'm going to close this, since I checked in the workaround, and also it looks like Yaapa has fixed the bug in strong-docs anyway.