On Thursday, September 20, 2018 at 9:26:56 AM UTC-5, Rasmus Schultz wrote: > > > It seems more "secure" to whitelist public thing, rather than blacklist > private thing > > The problem is that you're arguing with the language, where everything is > public - and not just by default. > > To start from the assumption that everything is internal is simply "wrong" > in the context of PHP - it simply isn't, it's public by default. > > That's not to say you couldn't deviate from that in doc-blocks, but it > would be inconsistent with the language - and, as said, inconsistent with > the way doc-blocks work in general, where you're generally starting with > PHP's own constraints being the default, and permitting you to narrow those > to set tighter constraints than is possible with PHP. > > When you're suggesting the opposite, you're really suggesting doc-blocks > should make the opposite assumption to what's true in the language. > > That would be confusing - and especially so, if this behavior is > conditional on whether any @api doc-blocks are present in the codebase; you > add the first @api doc-block and, boom, all your @internal doc-blocks are > now garbage. Doesn't make sense. Nobody likes side-effects. > > If this were a discussion about the default in the language, I'd be all > for private/internal being the default - but the language is set in stone, > and in my opinon, the php-doc standard should build and expand upon the > annotations that are possible in the language itself. It shouldn't replace > them. > > > On Thursday, September 20, 2018 at 7:17:43 AM UTC+2, Adrien Crivelli wrote: >> >> I agree with you that having both only lead to confusion. However we >> could certainly argue a long time about which one should be kept. >> >> When starting a project from scratch it's probably easier to mark a few >> method as public, rather than most code as private. It seems more "secure" >> to whitelist public thing, rather than blacklist private thing. On the >> other hand, like you said, for an existing project, it's likely easier to >> gradually make things private. Maybe that's the reason both annotations >> exist ? to allow to choose between "whitelist" or "blacklist" workflow ? >> >> But whatever reason may have lead to the current situation, I would be in >> favor to keep only one, whichever it is. >> >> It might even be possible to write a tool to migrate from one annotation >> to another, once the choice is settled. >> >
Historically speaking, @internal was the only tag available of the two, and was designed for making it possible for two levels of documentation: * public level code for consumers to read * private level code for developers-of-this-code to read This assumed that the default use of phpDocumentor was for producing the former, whereas adding the --parseprivate option would allow for creation of the latter. What this scheme did not address is "package scope", where publicly scoped elements are only public so that other classes in the package can use them, but the intention is *not* for consumers of the package to use them. Thus was born, in the wild, the custom @api tag. This was not recognized as anything specific/special in phpDocumentor until v2. Further, in v2, the tag still doesn't hide any public elements that are not marked with @api. The only behavior specified for this tag is that any output templates *that choose to* should list all @api elements in a special sidebar display. Honestly, I'm ok to *drop* the @api tag from the tag catalog, and let it live as a custom tag in the wild. It's really only in the PSR draft because the draft was sourced from phpDocumentor v2's manual. I've never personally used it to manage public vs package scope in my docs... I've instead used tighter runtime configurations for phpDocumentor to parse and show only the API-level elements that I want in my consumer's documentation. CRB -- You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/69001657-fab2-42b4-9448-72957380ee32%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
