Fixing doc comments

docs/reference/faq.md

@@ -112,11 +112,11 @@ For `git` integrations, Broker considers the following to be a "reference":
 - Any tag
 - Any branch `HEAD` commit
 
-Broker enumerates the list of references
+Broker first enumerates all references in the git repository.
 
 _Note that tags cannot be modified; once a tag has been created to "modify" it in `git` requires that the tag is_
 _deleted and then created with the same name. Such modifications are actually creation of the tag,_
-_and as such any tag that was "modified" is also scanned by Broker._
+_and as such any tag that was "modified" since the last scan is re-canned by Broker._
 
 After enumerating the list of references, Broker then uses its local database to filter any reference that it has already scanned.
 Note that this means that a modified tag would then be filtered at this step,

src/api/remote.rs

@@ -406,7 +406,7 @@ pub trait RemoteProvider {
         reference: &Self::Reference,
     ) -> Result<TempDir, Report<RemoteProviderError>>;
 
-    /// List references that have been updated
+    /// List all references
     async fn references(&self) -> Result<Vec<Self::Reference>, Report<RemoteProviderError>>;
 }
 

src/api/remote/git/repository.rs

@@ -69,7 +69,7 @@ impl Error {
     }
 }
 
-/// List references that have been updated
+/// List all references
 #[tracing::instrument]
 pub async fn list_references(transport: &Transport) -> Result<Vec<Reference>, Report<Error>> {
     get_all_references(transport).await

src/ext/command.rs

@@ -711,9 +711,9 @@ impl CommandDescriber for tokio::process::Command {
 }
 
 // Desugared, `&self` on `&T` means `&&T`.
-// We want to dereference using *self as opposed to self.deref()
-// This is because self.deref() will cause warnings about double references (&&T)
-// Whereas *self will not cause warnings as it is more explicit
+// Dereference using `*self` as opposed to `self.deref()`.
+// This is because `self.deref()` causes warnings about double references (`&&T`),
+// whereas `*self` does not since it is more explicit.
 //
 // Normally derefs are handled automatically, so we'd just write e.g. `self.stdout()`,
 // but in this case we want to be careful to access the `stdout()` method from the _underlying_ `&T`,
@@ -797,9 +797,9 @@ impl OutputProvider for std::process::Output {
 }
 
 // Desugared, `&self` on `&T` means `&&T`.
-// We want to dereference using *self as opposed to self.deref()
-// This is because self.deref() will cause warnings about double references (&&T)
-// Whereas *self will not cause warnings as it is more explicit
+// Dereference using `*self` as opposed to `self.deref()`.
+// This is because `self.deref()` causes warnings about double references (`&&T`),
+// whereas `*self` does not since it is more explicit.
 //
 // Normally derefs are handled automatically, so we'd just write e.g. `self.stdout()`,
 // but in this case we want to be careful to access the `stdout()` method from the _underlying_ `&T`,