phpdoc-parser

phpdoc-parser copied to clipboard

Since functions, methods and classes can have the @deprecated tag, some may want to only include the non-deprecated stuff in the final import. An --ignore-deprecated=true (default = false) flag when generating the JSON file would be handy, and would be handled in a similar way to how the @internal tag is supported.

Vaguely related: #11.

Had you seen specific use cases or just hypothetical? I would think deprecated code is still important to be in reference, it's omission could be very confusing.

The Genesis Framework has a deprecated.php file where each and every function inside of it is tagged with @deprecated. The same would apply to the contents of wp-includes/deprecated.php.

Some codebases being parsed by WP-Parser would most definitely not want deprecated functions included, since they've been deprecated for a reason, to avoid increasing their visibility. Others, like you, think that they should still be included (you're wrong btw ;-) ), hence the usefulness of an option that can include or exclude them.

For instance, although wp_get_linksbyname(), user_can_delete_post_comments(), get_the_author_msn() and permalink_link() (among others) all exist in WP, I wouldn't expect DevHub to be making anyone aware of their existence, because they are deprecated.

I find limiting information about source counter-productive. You cannot hide deprecated from people, they will encounter it anyway and need to be educated about it.

How do you expect someone to move on from using deprecated function without documenting that it is deprecated and providing recommended replacement?

DevHub will absolutely be including them, so does QueryPosts.

On that note I don't see this as part of parsing process. I don't remember if deprecated stuff is properly detected and meta-data-ed now (probably not), but it will be. From there you can do what you want with data parser gives you, such as not showing deprecated items or blocking their creation altogether.

In a nutshell we can make convenient to get rid of them, just not via complicating parsing stage.

I'd be expecting the parser to work the same as how the optional @internal flag already works.

I am afraid to look how that is, but I'll probably have to later. :)

#16