Minor docs fixes (#1571)

Signed-off-by: John Kastner <[email protected]>

Author: john-h-kastner-aws

cedar-policy-validator/src/entity_manifest.rs

@@ -42,8 +42,8 @@ use crate::{
 };
 use crate::{ValidationResult, Validator};
 
-/// Data structure storing what data is needed
-/// based on the the [`RequestType`].
+/// Data structure storing what data is needed based on the the [`RequestType`].
+///
 /// For each request type, the [`EntityManifest`] stores
 /// a [`RootAccessTrie`] of data to retrieve.
 ///
@@ -94,9 +94,9 @@ impl Display for EntityRoot {
     }
 }
 
-/// A [`RootAccessTrie`] is a trie describing a set of
-/// data paths to retrieve. Each edge in the trie
-/// is either a record or entity dereference.
+/// A trie describing a set of data paths to retrieve.
+///
+/// Each edge in the trie is either a record or entity dereference.
 ///
 /// If an entity or record field does not exist in the backing store,
 /// it is safe to stop loading data at that point.

cedar-policy/src/api.rs

@@ -697,7 +697,7 @@ impl Entities {
     ///   "parents": [{"type":"Group","id":"admin"}]
     /// },
     /// {
-    ///   "uid": {"type":"Groupd","id":"admin"},
+    ///   "uid": {"type":"Group","id":"admin"},
     ///   "attrs": {},
     ///   "parents": []
     /// }
@@ -2916,15 +2916,15 @@ impl Template {
 
     /// Get an annotation value of this `Template`.
     /// If the annotation is present without an explicit value (e.g., `@annotation`),
-    /// then this function returns `Some("")`. It returns `None` only when the
-    /// annotation is not present.
+    /// then this function returns `Some("")`. Returns `None` when the
+    /// annotation is not present or when `key` is not a valid annotation identifier.
     pub fn annotation(&self, key: impl AsRef<str>) -> Option<&str> {
         self.ast
             .annotation(&key.as_ref().parse().ok()?)
             .map(AsRef::as_ref)
     }
 
-    /// Iterate through annotation data of this `Template` as key-value pairs
+    /// Iterate through annotation data of this `Template` as key-value pairs.
     /// Annotations which do not have an explicit value (e.g., `@annotation`),
     /// are included in the iterator with the value `""`.
     pub fn annotations(&self) -> impl Iterator<Item = (&str, &str)> {
@@ -3255,17 +3255,17 @@ impl Policy {
         self.ast.effect()
     }
 
-    /// Get an annotation value of this template-linked or static policy
+    /// Get an annotation value of this template-linked or static policy.
     /// If the annotation is present without an explicit value (e.g., `@annotation`),
-    /// then this function returns `Some("")`. It returns `None` only when the
-    /// annotation is not present.
+    /// then this function returns `Some("")`. Returns `None` when the
+    /// annotation is not present or when `key` is not a valid annotations identifier.
     pub fn annotation(&self, key: impl AsRef<str>) -> Option<&str> {
         self.ast
             .annotation(&key.as_ref().parse().ok()?)
             .map(AsRef::as_ref)
     }
 
-    /// Iterate through annotation data of this template-linked or static policy
+    /// Iterate through annotation data of this template-linked or static policy.
     /// Annotations which do not have an explicit value (e.g., `@annotation`),
     /// are included in the iterator with the value `""`.
     pub fn annotations(&self) -> impl Iterator<Item = (&str, &str)> {

cedar-policy/src/api/err.rs

@@ -352,6 +352,7 @@ mod context_creation_errors {
 }
 
 /// Error subtypes for [`ValidationError`].
+///
 /// Errors are primarily documented on their variants in [`ValidationError`].
 pub mod validation_errors;
 
@@ -528,12 +529,15 @@ impl From<cedar_policy_validator::ValidationError> for ValidationError {
 }
 
 /// Error subtypes for [`ValidationWarning`].
+///
 /// Validation warnings are primarily documented on their variants in [`ValidationWarning`].
 pub mod validation_warnings;
 
 /// Represents the different kinds of validation warnings and information
-/// specific to that warning. Marked as `non_exhaustive` to allow adding
-/// additional warnings in the future as a non-breaking change.
+/// specific to that warning.
+///
+/// Marked as `non_exhaustive` to allow adding additional warnings in the future
+/// as a non-breaking change.
 #[derive(Debug, Clone, Error, Diagnostic)]
 #[non_exhaustive]
 pub enum ValidationWarning {
@@ -884,6 +888,7 @@ impl ParseErrors {
 }
 
 /// Errors that can occur when parsing policies or expressions.
+///
 /// Marked as `non_exhaustive` to support adding additional error information
 /// in the future without a major version bump.
 #[derive(Debug, Diagnostic, Error, RefCast)]