Looking through my code I noticed that most of my @NoDoc facets are immediately followed by a comment explaining why it's there.

@NoDoc // Advanced use only

And I noticed a lot of the Fantom code does the same, example: ActorPool.maxMsgsBeforeYield

So I was wondering if maybe @NoDoc should have a msg field similar to @Deprecated? I know fandoc comments with @NoDoc still appear in .apidoc files, they just aren't compiled into the standard documentation. So maybe IDEs could use the msg somehow in the future?

I guess it wouldn't hurt anything - although by definition its not supposed to be documented, so seems like a catch-22 :)