Fix cargo --doc warnings (#1289)

* Fix cargo --doc warnings

* Update src/parser/uniterm.rs

Co-authored-by: Viktor Kleen <viktor.kleen@tweag.io>

---------

Co-authored-by: Viktor Kleen <viktor.kleen@tweag.io>

src/cache.rs

@@ -852,7 +852,7 @@ impl Cache {
     }
 
     /// Get a mutable reference to the underlying files. Required by
-    /// [crate::error::ToDiagnostic::to_diagnostic].
+    /// [crate::error::IntoDiagnostics::into_diagnostics].
     pub fn files_mut(&mut self) -> &mut Files<String> {
         &mut self.files
     }

src/eval/cache/lazy.rs

@@ -88,7 +88,7 @@ pub struct ThunkData {
 /// it reveals more static information about the record (such as the list of fields) without having
 /// to provide any argument first. Then, splitting `self` and removing the function altogether when
 /// the field doesn't depend on other fields is more precise with respect to dependency tracking
-/// (this has an important positive memory impact, see [crate::term::FieldDeps]).
+/// (this has an important positive memory impact, see [crate::term::record::FieldDeps]).
 ///
 /// In practice, Nickel uses the last representation. Fields that don't have any free variable
 /// intersecting with the name of the other fields are allocated as normal thunks that will only be

src/eval/fixpoint.rs

@@ -163,8 +163,9 @@ pub fn rec_env<'a, I: Iterator<Item = (&'a Ident, &'a Field)>, C: Cache>(
 }
 
 /// Update the environment of the content of a recursive record field by extending it with a
-/// recursive environment. When seeing revertible elements as a memoizing device for functions, this
-/// step correspond to function application (see documentation of [crate::eval::lazy::ThunkData]).
+/// recursive environment. When seeing revertible elements as a memoizing device for functions,
+/// this step correspond to function application (see documentation of
+/// [crate::eval::cache::lazy::ThunkData]).
 ///
 /// For each field, retrieve the set set of dependencies from the corresponding element in the
 /// environment, and only add those dependencies to the environment. This avoids retaining

src/parser/uniterm.rs

@@ -38,10 +38,11 @@ use std::{cell::RefCell, convert::TryFrom};
 ///
 /// As soon as this variable is used in a compound expression, the top-level rule tells us how to
 /// translate it. For example, if we see an arrow `a -> Num`, then we will convert it to a type
-/// variable, and return `UniTermNode::Types(TypeF::Arrow(..))` (there is actually a subtlety:
-/// see [`FixTypeVars::fix_type_vars`], but let's ignore it here). If, on the other hand, we enter the rule for
-/// an infix operator as in `a + 1`, `a` will be converted to a `Term::Var` and the resulting
-/// uniterm will be `UniTermNode::Term(Term::Op2(..))`.
+/// variable, and return `UniTermNode::Types(TypeF::Arrow(..))` (there is actually a subtlety: see
+/// the in-code documentation of the private symbol `FixTypeVars::fix_type_vars`, but let's ignore it
+/// here). If, on the other hand, we enter the rule for an infix operator as in `a + 1`, `a` will
+/// be converted to a `Term::Var` and the resulting uniterm will be
+/// `UniTermNode::Term(Term::Op2(..))`.
 pub enum UniTermNode {
     /// A variable. Can refer both to a term variable or a type variable.
     Var(Ident),
@@ -439,8 +440,8 @@ impl TryFrom<UniRecord> for RichTerm {
     /// isn't syntactically a record type either. Elaborate field paths `foo.bar = value` to the
     /// expanded form `{foo = {bar = value}}`.
     ///
-    /// We also fix the type variables of the type appearing inside annotations (see
-    /// [`FixTypeVars::fix_type_vars`]).
+    /// We also fix the type variables of the type appearing inside annotations (see in-code
+    /// documentation of the private symbol `FixTypeVars::fix_type_vars`).
     fn try_from(ur: UniRecord) -> Result<Self, ParseError> {
         let pos = ur.pos;
 
@@ -781,8 +782,8 @@ impl FixTypeVars for EnumRows {
     }
 }
 
-/// Fix the type variables of types appearing as annotations of record fields. See
-/// [`Types::fix_type_vars`].
+/// Fix the type variables of types appearing as annotations of record fields. See the in-code
+/// documentation of the private symbol `Types::fix_type_vars`.
 pub fn fix_field_types(metadata: &mut FieldMetadata, span: RawSpan) -> Result<(), ParseError> {
     if let Some(LabeledType { ref mut types, .. }) = metadata.annotation.types {
         types.fix_type_vars(span)?;

src/program.rs

@@ -105,8 +105,8 @@ impl QueryPath {
         path_as_idents.map(QueryPath)
     }
 
-    /// As [`parse`], but accepts an `Option` to accomodate for the absence of path. If the input
-    /// is `None`, `Ok(QueryPath::default())` is returned (that is, an empty query path).
+    /// As [`Self::parse`], but accepts an `Option` to accomodate for the absence of path. If the
+    /// input is `None`, `Ok(QueryPath::default())` is returned (that is, an empty query path).
     pub fn parse_opt(cache: &mut Cache, input: Option<String>) -> Result<Self, ParseError> {
         Ok(input
             .map(|path| Self::parse(cache, path))

src/repl/query_print.rs

@@ -160,10 +160,8 @@ impl Default for Attributes {
     }
 }
 
-/// Print the result of a metadata query, which is a "weakly" evaluated term (see
-/// [`crate::eval::VirtualMachine::eval_meta`] and [`crate::program::query`]).
-///
-/// Wrapper around `write_query_result_` that selects an adapted query printer at compile time.
+/// Render the result of a metadata query, automatically selecting an adapted query printer at
+/// compile time.
 pub fn write_query_result(
     out: &mut impl Write,
     field: &Field,
@@ -175,11 +173,11 @@ pub fn write_query_result(
     #[cfg(not(feature = "markdown"))]
     let renderer = SimpleRenderer {};
 
-    write_query_result_(out, field, selected_attrs, &renderer)
+    render_query_result(out, field, selected_attrs, &renderer)
 }
 
-/// Print the result of a metadata query.
-fn write_query_result_<R: QueryPrinter>(
+/// Render the result of a metadata query.
+fn render_query_result<R: QueryPrinter>(
     out: &mut impl Write,
     field: &Field,
     selected_attrs: Attributes,

src/term/mod.rs

@@ -494,7 +494,7 @@ impl TypeAnnotation {
     }
 
     /// Build a list of pending contracts from this annotation, to be stored alongside the metadata
-    /// of a field. Similar to [all_contracts], but including the contracts from `self.contracts`
+    /// of a field. Similar to [Self::all_contracts], but including the contracts from `self.contracts`
     /// only, while `types` is excluded. Contracts derived from type annotations aren't treated the
     /// same since they don't propagate through merging.
     pub fn pending_contracts(&self) -> Result<Vec<RuntimeContract>, UnboundTypeVariableError> {
@@ -1351,8 +1351,8 @@ pub enum BinaryOp {
     /// Append a note to the current diagnostic of a label.
     LabelAppendNote(),
 
-    /// Look up the [`TypeVarData`] associated with a [`SealingKey`] in the
-    /// type environment of a [label](Term::Lbl)
+    /// Look up the [`crate::label::TypeVarData`] associated with a [`SealingKey`] in the type
+    /// environment of a [label](Term::Lbl)
     LookupTypeVar(),
 }
 
@@ -1412,13 +1412,13 @@ pub enum NAryOp {
     ///     something goes wrong while unsealing,
     ///   - the [record](Term::Record) whose tail we wish to unseal.
     RecordUnsealTail(),
-    /// Insert type variable data into the [`type_environment`] of a [`Label`]
+    /// Insert type variable data into the `type_environment` of a [`crate::label::Label`]
     ///
     /// Takes four arguments:
     ///   - the [sealing key](Term::SealingKey) assigned to the type variable
-    ///   - the [introduction polarity](label::Polarity) of the type variable
-    ///   - the [kind](types::VarKind) of the type variable
-    ///   - a [label](Term::Label) on which to operate
+    ///   - the [introduction polarity](crate::label::Polarity) of the type variable
+    ///   - the [kind](crate::types::VarKind) of the type variable
+    ///   - a [label](Term::Lbl) on which to operate
     InsertTypeVar(),
     /// Return a sub-array corresponding to a range. Given that Nickel uses array slices under the
     /// hood, as long as the array isn't modified later, this operation is constant in time and

src/transform/import_resolution.rs

@@ -69,7 +69,7 @@ pub mod strict {
     }
 
     /// Resolve the import if the term is an unresolved import, or return the term unchanged. As
-    /// [`super::share_normal_form::transform_one`], this function is not recursive.
+    /// [`crate::transform::share_normal_form::transform_one`], this function is not recursive.
     pub fn transform_one<R>(
         rt: RichTerm,
         resolver: &mut R,

src/typecheck/mod.rs

@@ -15,7 +15,7 @@
 //!   mode is implemented by [`type_check`] and variants.
 //! - **walk** doesn't enforce any typing but traverses the AST looking for typed blocks to
 //!   typecheck. Walk mode also stores the annotations of bound identifiers in the environment. This
-//!   is implemented by the [`walk`] function.
+//!   is implemented by the `walk` function.
 //!
 //! The algorithm starts in walk mode. A typed block (an expression annotated with a type) switches
 //! to enforce mode, and is switched back to walk mode when entering an expression annotated with a