trust_anchor/end_entity: rework deprecation notes.

In 0.101.2 we deprecated the `TlsServerTrustAnchors` and
`TlsClientTrustAnchors` types along with the
`EndEntity::verify_is_valid_tls_server_cert` and
`EndEntity::verify_is_valid_tls_client_cert` functions that used them.

However, only the `EndEntity` deprecations had a `note` pointing to the
preferred replacement, and the text was quite terse.

This commit adds notes to the trust anchor types that were missing
these, and updates the end entity verification deprecation notes to be
more user-friendly.

Author: cpu

src/end_entity.rs

@@ -143,7 +143,13 @@ impl<'a> EndEntityCert<'a> {
     /// `time` is the time for which the validation is effective (usually the
     /// current time).
     #[allow(deprecated)]
-    #[deprecated(since = "0.101.2", note = "Use `verify_for_usage` instead")]
+    #[deprecated(
+        since = "0.101.2",
+        note = "The per-usage trust anchor representations and verification functions are deprecated in \
+        favor of the general-purpose `TrustAnchor` type and `EndEntity::verify_for_usage` function. \
+        The new `verify_for_usage` function expresses trust anchor and end entity purpose with the \
+        key usage argument."
+    )]
     pub fn verify_is_valid_tls_server_cert(
         &self,
         supported_sig_algs: &[&SignatureAlgorithm],
@@ -173,7 +179,13 @@ impl<'a> EndEntityCert<'a> {
     /// the time for which the validation is effective (usually the current
     /// time).
     #[allow(deprecated)]
-    #[deprecated(since = "0.101.2", note = "Use `verify_for_usage` instead")]
+    #[deprecated(
+        since = "0.101.2",
+        note = "The per-usage trust anchor representations and verification functions are deprecated in \
+        favor of the general-purpose `TrustAnchor` type and `EndEntity::verify_for_usage` function. \
+        The new `verify_for_usage` function expresses trust anchor and end entity purpose with the \
+        key usage argument."
+    )]
     pub fn verify_is_valid_tls_client_cert(
         &self,
         supported_sig_algs: &[&SignatureAlgorithm],

src/trust_anchor.rs

@@ -24,12 +24,24 @@ pub struct TrustAnchor<'a> {
 }
 
 /// Trust anchors which may be used for authenticating servers.
-#[deprecated(since = "0.101.2")]
+#[deprecated(
+    since = "0.101.2",
+    note = "The per-usage trust anchor representations and verification functions are deprecated in \
+        favor of the general-purpose `TrustAnchor` type and `EndEntity::verify_for_usage` function. \
+        The new `verify_for_usage` function expresses trust anchor and end entity purpose with the \
+        key usage argument."
+)]
 #[derive(Debug)]
 pub struct TlsServerTrustAnchors<'a>(pub &'a [TrustAnchor<'a>]);
 
 /// Trust anchors which may be used for authenticating clients.
-#[deprecated(since = "0.101.2")]
+#[deprecated(
+    since = "0.101.2",
+    note = "The per-usage trust anchor representations and verification functions are deprecated in \
+        favor of the general-purpose `TrustAnchor` type and `EndEntity::verify_for_usage` function. \
+        The new `verify_for_usage` function expresses trust anchor and end entity purpose with the \
+        key usage argument."
+)]
 #[derive(Debug)]
 pub struct TlsClientTrustAnchors<'a>(pub &'a [TrustAnchor<'a>]);