New @warning, @caution, @unsafe, or @risky annotation

[jrcii]

"Deprecated" originally meant "not recommended" in standard English, but, as phpDoc's docs itself explains, has come to mean in tech, "slated for removal", so we can't use @deprecated to mean only the former and not the latter.

It would be useful to have a standard that IDEs could recognize (and maybe specially highlight) that means "use this with caution / make sure you want to use/do this." I've seen IDEs, for example, employ this with SQL SETs without conditions, but those are hard-coded inspections, not generated from phpDoc.

[jrcii]

The pattern of marking code with these designations is found in various programming contexts, for example,

In React:
https://www.geeksforgeeks.org/reactjs-unsafe_componentwillmount-method/
https://blog.logrocket.com/using-dangerouslysetinnerhtml-in-a-react-application/

In Rust:
https://doc.rust-lang.org/book/ch19-01-unsafe-rust.html

In Swift:
https://developer.apple.com/documentation/swift/unsafepointer