Loopback: Glitch in API docs

[crandmck]

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?

[superkhau]

Yeah, it should be removed from the API docs.

[bajtos]

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]

I thought that /*! should be ignored by jsdoc parser used by strong-docs

I thought so, too. Not sure why it's picking up this block. Could be a bug in strong-docs?

[superkhau]

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.

Exactly this. Can we just use normal //?

[crandmck]

Can we just use normal //?

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.

[crandmck]

I went ahead and fixed this with the "workaround" with 1b55d35542505044046645612aa9371f35310550

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]

@crandmck that's just the way dox (which sdocs uses) works. Do not use the /* */ comments if not intended as a JSdoc block.

[crandmck]

Wait, doc comments are

/**
...comments
/*

NOT /* in the leading comment line.
Anyway, the original comment here started with /*! and dox specifically states that /*! comments are ignored; see https://www.npmjs.com/package/dox#ignore.

[hacksparrow]

I was looking at the updated code, let me review with the previous code.

[hacksparrow]

/*!
* Expose path to the default favicon file
*
* ***only in node***
*/

is being ignored on my local machine. However, I am using the latest unpublished version of sdocs.

If https://github.com/strongloop-internal/strong-docs/pull/74 is merged, you can use the version I am using.

[crandmck]

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.