Skip to content

Glitch in API docs #2534

Closed
Closed

Description

@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?

Activity

  1. self-assigned this
    on Jul 22, 2016
  2. superkhau commented on Jul 22, 2016

    @superkhau
    Contributor

    Yeah, it should be removed from the API docs.

  3. bajtos commented on Jul 25, 2016

    @bajtos
    Member

    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

  4. crandmck commented on Jul 25, 2016

    @crandmck
    ContributorAuthor

    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?

  5. superkhau commented on Jul 25, 2016

    @superkhau
    Contributor

    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 //?

  6. crandmck commented on Jul 25, 2016

    @crandmck
    ContributorAuthor

    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.

  7. added a commit that references this issue on Jul 26, 2016
  8. crandmck commented on Jul 26, 2016

    @crandmck
    ContributorAuthor

    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.

  9. hacksparrow commented on Aug 1, 2016

    @hacksparrow
    Member

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

  10. crandmck commented on Aug 1, 2016

    @crandmck
    ContributorAuthor

    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.

  11. hacksparrow commented on Aug 1, 2016

    @hacksparrow
    Member

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

  12. hacksparrow commented on Aug 1, 2016

    @hacksparrow
    Member
    /*!
    * 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 strongloop/strong-docs#74 is merged, you can use the version I am using.

  13. crandmck commented on Aug 2, 2016

    @crandmck
    ContributorAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions