doc comment improvements

clippy (in pedantic mode) suggested that the section "Possible Errors" should be just "Errors" instead.
DanielT · May 9, 2024 · 676ad99 · 676ad99
1 parent e05c229
commit 676ad99
Show file tree

Hide file tree

Showing 5 changed files with 39 additions and 39 deletions.
diff --git a/autosar-data/src/arxmlfile.rs b/autosar-data/src/arxmlfile.rs
@@ -60,7 +60,7 @@ impl ArxmlFile {
     /// file.set_version(AutosarVersion::Autosar_00050);
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::VersionIncompatibleData`] the existing data is not compatible with the new version
     ///
@@ -147,7 +147,7 @@ impl ArxmlFile {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     /// [`AutosarDataError::ItemDeleted`]: The model is no longer valid
     ///

diff --git a/autosar-data/src/autosarmodel.rs b/autosar-data/src/autosarmodel.rs
@@ -70,7 +70,7 @@ impl AutosarModel {
     /// # Parameters
     ///
     ///  - `filename`: A filename for the data from the buffer. It must be unique within the model.
-    ///    It will be used by write(), and is also used to identify this data in error messages.
+    ///    It will be used by `write()`, and is also used to identify this data in error messages.
     ///  - `version`: The [`AutosarVersion`] that will be used by the data created inside this file
     ///
     /// # Example
@@ -84,7 +84,7 @@ impl AutosarModel {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::DuplicateFilenameError`]: The model already contains a file with this filename
     ///  - [`AutosarDataError::VersionMismatch`]: The new file cannot be creatd with a version that differs from the version of existing data
@@ -137,7 +137,7 @@ impl AutosarModel {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::DuplicateFilenameError`]: The model already contains a file with this filename
     ///  - [`AutosarDataError::OverlappingDataError`]: The new data contains Autosar paths that are already defined by the existing data
@@ -449,7 +449,7 @@ impl AutosarModel {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::IoErrorOpen`]: The file could not be opened
     ///  - [`AutosarDataError::IoErrorRead`]: There was an error while reading the file
@@ -559,7 +559,7 @@ impl AutosarModel {
     ///
     /// This is a wrapper around `serialize_files`. The current filename of each file will be used to write the serialized data.
     ///
-    /// If any of the individual files cannot be written, then write() will abort and return the error.
+    /// If any of the individual files cannot be written, then `write()` will abort and return the error.
     /// This may result in a situation where some files have been written and others have not.
     ///
     /// # Example
@@ -683,7 +683,7 @@ impl AutosarModel {
         self.root_element().elements_dfs()
     }
 
-    /// Recursively sort all elements in the model. This is exactly identical to calling sort() on the root element of the model.
+    /// Recursively sort all elements in the model. This is exactly identical to calling `sort()` on the root element of the model.
     ///
     /// All sub elements of the root element are sorted alphabetically.
     /// If the sub-elements are named, then the sorting is performed according to the item names,

diff --git a/autosar-data/src/element.rs b/autosar-data/src/element.rs
@@ -32,7 +32,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     pub fn parent(&self) -> Result<Option<Element>, AutosarDataError> {
@@ -64,7 +64,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     pub fn named_parent(&self) -> Result<Option<Element>, AutosarDataError> {
@@ -167,7 +167,7 @@ impl Element {
     /// }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -239,7 +239,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: Th ecurrent element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -265,7 +265,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -334,7 +334,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -371,7 +371,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -412,7 +412,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -454,7 +454,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -508,7 +508,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -559,7 +559,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -606,7 +606,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -658,7 +658,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -706,7 +706,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -743,7 +743,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -821,7 +821,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -881,7 +881,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -967,7 +967,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -1018,7 +1018,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::IncorrectContentType`] the element `content_type` is not Mixed
     ///  - [`AutosarDataError::InvalidPosition`] the position is not valid
@@ -1060,7 +1060,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::IncorrectContentType`] the element `content_type` is not Mixed
     ///  - [`AutosarDataError::InvalidPosition`] the position is not valid
@@ -1298,7 +1298,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -1340,7 +1340,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -1442,7 +1442,7 @@ impl Element {
     /// # assert!(result.is_ok());
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::InvalidAttribute`]: The `AttributeName` is not valid for this element
@@ -1468,7 +1468,7 @@ impl Element {
     /// # assert!(result.is_ok());
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::InvalidAttribute`]: The `AttributeName` is not valid for this element
@@ -1865,7 +1865,7 @@ impl Element {
     /// # Ok(())
     /// # }
     /// ```
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -1933,7 +1933,7 @@ impl Element {
     /// element.add_to_file(&file);
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -2024,7 +2024,7 @@ impl Element {
     /// element.remove_from_file(&file);
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     ///  - [`AutosarDataError::ItemDeleted`]: The current element is in the deleted state and will be freed once the last reference is dropped
     ///  - [`AutosarDataError::ParentElementLocked`]: a parent element was locked and did not become available after waiting briefly.
@@ -2110,7 +2110,7 @@ impl Element {
     /// # }
     /// ```
     ///
-    /// # Possible Errors
+    /// # Errors
     ///
     /// - [`AutosarDataError::ElementInsertionConflict`]: The sub element conflicts with an existing sub element
     /// - [`AutosarDataError::InvalidSubElement`]: The sub element is not valid inside this element

diff --git a/autosar-data/src/elementraw.rs b/autosar-data/src/elementraw.rs
@@ -22,10 +22,10 @@ use crate::{
 ///
 /// Note regarding deadlock avoidance:
 /// Consider the case where two element operations are started in parallel on different threads.
-/// One calls file() or path() and traverses the hierarchy of elements upward
+/// One calls `file()` or `path()` and traverses the hierarchy of elements upward
 /// root <- element <- element <- current element (locked)
 ///
-/// The other calls e.g. `create_copied_sub_element`() or `remove_sub_element`() and wants to lock all of its sub elements
+/// The other calls e.g. `create_copied_sub_element()` or `remove_sub_element()` and wants to lock all of its sub elements
 /// root -> current element (locked) -> element -> element
 ///
 /// These two operations could deadlock if they operate on the same tree of elements.

diff --git a/autosar-data/src/lib.rs b/autosar-data/src/lib.rs
@@ -304,7 +304,7 @@ pub struct Element(Arc<RwLock<ElementRaw>>);
 /// (see the documentation of [`std::sync::Arc`] for an explanation of weak references)
 ///
 /// This `WeakElement` can be held indefinitely without forcing the referenced data to remain valid.
-/// When access is needed, the method upgrade() will attempt to get a strong reference and return an [Element]
+/// When access is needed, the method `upgrade()` will attempt to get a strong reference and return an [Element]
 #[derive(Clone)]
 pub struct WeakElement(Weak<RwLock<ElementRaw>>);