Option to only output docs on items labeled @public

[jamiebuilds]

I'm setting up documentation on Babel right now, and we want to make sure that things stay private until we explicitly label them @public

[tmcw]

Interesting, this is totally doable on a code level.. options for CLI style:

• Along with the --private flag that already exists, add --public that only publishes explicitly public docs
• Replace the --private flag with an --access flag that could be used like --access=private, --access=public,private, --access=all, --access=public

[anandthakker]

To me, this is about controlling whether untagged items are treated as private or public, distinct from filtering output by access level. In this line of thinking, how about something like --default-access=private?

[jamiebuilds]

I think --access would cover just about everything. You could even easily generate different docs for either users or maintainers.

Does the access default to anything? I assume it would just be a null value.

[anandthakker]

@thejameskyle I think the (possibly minor/semantic) problem with --access is that it still leaves it ambiguous what to do with jsdoc items that are not tagged with private or public: If --access=public means "anything that's not private", then it doesn't solve the original problem you posted; if it means "only things that are explicitly marked public," then --access=private,public would weirdly leave out anything that's not explicitly tagged, which probably doesn't make sense.

Any of the following use cases are plausible to me (even if a couple of them are a bit odd):

• Everything, regardless of access level
• Everything that isn't specifically marked @private (default)
• Only things marked @public ( @thejameskyle 's original use case )
• Everything that isn't specifically marked @public -- e.g., just the internal API, assuming that by default things are private
• Only things marked @private -- same as previous, but assuming that by default things are public

[jamiebuilds]

I think it's weird to mark things as public or private when they don't explicitly have the label. I would just make --access support untagged items. --access public,private,null,or-whatever-name

[jfirebaugh]

@public is the JSDoc default. To keep things simple, I think we should continue to require explicit @private tagging to keep things private, and consider this a won't fix. @thejameskyle, you may want to also consider using /* comments (rather than /**) if you want to use JSDoc syntax but not include them in public documentation.

[jamiebuilds]

Why would you limit yourself to what JSDoc does? You have the opportunity to be a much better tool and I can see lots of users building public-facing docs wanting this. Please don't close this as wontfix, I want to be able to use documentationjs

[jfirebaugh]

To me the considerations are:

• Maintaining JSDoc semantic compatibility. This is more about JSDoc-the-language than JSDoc-the-tool, and the value is in matching developer expectations of how JSDoc-the-language works for migrations to and from other JSDoc tools.
• Every feature has a cost, this one included.
• Its easy to get the behavior you desire within the existing feature set by using /* rather than /** until you've done the necessary auditing.

Together, these considerations lead me to believe we should omit this feature, but I'm happy to defer to fellow contributors if they disagree.

[jamiebuilds]

Maintaining JSDoc semantic compatibility. This is more about JSDoc-the-language than JSDoc-the-tool, and the value is in matching developer expectations of how JSDoc-the-language works for migrations to and from other JSDoc tools.

Okay, then my understanding is that what @anandthakker proposed would do just that.

Every feature has a cost, this one included.

This would be a hugely beneficial feature, I would hope that it is valuable enough for you to support it. I'd certainly be willing to support something this valuable in Babel so that documentationjs could use it.

Its easy to get the behavior you desire within the existing feature set by using /* rather than /** until you've done the necessary auditing.

It's also very easy to make the mistake of not doing that. I had to go through a lot of existing comments and update them hoping that I could remove it later

[jfirebaugh]

I noticed that JSDoc (the tool) has an --access command line flag like the one that's proposed here, with a possible value of undefined. So I guess the "@public default" really is just a tooling level default, and at a language level it's fine to default to "undefined". This definitely brings me around to @thejameskyle's viewpoint -- I withdraw my objection.

[jonschlinkert]

fwiw we use @api public (similar to dox) since there might be other options beyond just private and public, like developer or user for example.