Update documentation to include alternative, supported way(s) of accomplishing what is now deprecated. If no alternative is available, include a note indicating that use of the deprecated API should be avoided. Updating the documentation includes adding a \deprecated tag with the aforementioned notes to the Doxygen for any public declarations associated with the feature.
This is good and will apply to many things within iRODS code. However, there are cases where the rules should be relaxed. For example, when replacing utility functions in iRODS with functions from an external library (e.g. Boost). For these cases, it doesn't make much sense to mention an alternative because there are likely an infinite number of alternatives. Also, the developer's environment may not be able to support the mentioned alternative (e.g. Boost can't be used in C code).
As for requiring the deprecation message to say "use should be avoided", deprecation implies that, therefore there's no real reason to state it. The compiler will inform users when they are using deprecated functionality.
As for the doxygen documentation, that should only apply if doxygen documentation existed before the deprecation.
Step 1 of the deprecation rules states:
This is good and will apply to many things within iRODS code. However, there are cases where the rules should be relaxed. For example, when replacing utility functions in iRODS with functions from an external library (e.g. Boost). For these cases, it doesn't make much sense to mention an alternative because there are likely an infinite number of alternatives. Also, the developer's environment may not be able to support the mentioned alternative (e.g. Boost can't be used in C code).
As for requiring the deprecation message to say "use should be avoided", deprecation implies that, therefore there's no real reason to state it. The compiler will inform users when they are using deprecated functionality.
As for the doxygen documentation, that should only apply if doxygen documentation existed before the deprecation.