Document nested block comments and add more intra docs links (ron-rs#440

)

README.md

@@ -141,6 +141,10 @@ fn main() {
     let x: MyStruct = ron::from_str("(boolean: true, float: 1.23)").unwrap();
 
     println!("RON: {}", ron::to_string(&x).unwrap());
+
+    println!("Pretty RON: {}", ron::ser::to_string_pretty(
+        &x, ron::ser::PrettyConfig::default()).unwrap(),
+    );
 }
 ```
 

docs/grammar.md

@@ -18,7 +18,8 @@ RON = [extensions], ws, value, ws;
 ```ebnf
 ws = { ws_single | comment };
 ws_single = "\n" | "\t" | "\r" | " ";
-comment = ["//", { no_newline }, "\n"] | ["/*", { ? any character ? }, "*/"];
+comment = ["//", { no_newline }, "\n"] | ["/*", nested_block_comment, "*/"];
+nested_block_comment = { ? any characters except "/*" or "*/" ? }, [ "/*", nested_block_comment, "*/", nested_block_comment ];
 ```
 
 ## Commas

src/de/mod.rs

@@ -22,7 +22,7 @@ mod value;
 /// The RON deserializer.
 ///
 /// If you just want to simply deserialize a value,
-/// you can use the `from_str` convenience function.
+/// you can use the [`from_str`] convenience function.
 pub struct Deserializer<'de> {
     bytes: Bytes<'de>,
     newtype_variant: bool,
@@ -128,9 +128,9 @@ impl<'de> Deserializer<'de> {
         }
     }
 
-    /// Called from `deserialize_any` when a struct was detected. Decides if
-    /// there is a unit, tuple or usual struct and deserializes it
-    /// accordingly.
+    /// Called from [`deserialize_any`][serde::Deserializer::deserialize_any]
+    /// when a struct was detected. Decides if there is a unit, tuple or usual
+    /// struct and deserializes it accordingly.
     ///
     /// This method assumes there is no identifier left.
     fn handle_any_struct<V>(&mut self, visitor: V) -> Result<V::Value>
@@ -155,8 +155,11 @@ impl<'de> Deserializer<'de> {
         }
     }
 
-    /// Called from `deserialize_struct`, `struct_variant`, and `handle_any_struct`.
-    /// Handles deserialising the enclosing parentheses and everything in between.
+    /// Called from
+    /// [`deserialize_struct`][serde::Deserializer::deserialize_struct],
+    /// [`struct_variant`][serde::de::VariantAccess::struct_variant], and
+    /// [`handle_any_struct`][Self::handle_any_struct]. Handles
+    /// deserialising the enclosing parentheses and everything in between.
     ///
     /// This method assumes there is no struct name identifier left.
     fn handle_struct_after_name<V>(

src/options.rs

@@ -162,7 +162,11 @@ impl Options {
         Ok(value)
     }
 
-    /// Serializes `value` into `writer`
+    /// Serializes `value` into `writer`.
+    ///
+    /// This function does not generate any newlines or nice formatting;
+    /// if you want that, you can use
+    /// [`to_writer_pretty`][Self::to_writer_pretty] instead.
     pub fn to_writer<W, T>(&self, writer: W, value: &T) -> Result<()>
     where
         W: io::Write,
@@ -185,7 +189,8 @@ impl Options {
     /// Serializes `value` and returns it as string.
     ///
     /// This function does not generate any newlines or nice formatting;
-    /// if you want that, you can use `to_string_pretty` instead.
+    /// if you want that, you can use
+    /// [`to_string_pretty`][Self::to_string_pretty] instead.
     pub fn to_string<T>(&self, value: &T) -> Result<String>
     where
         T: ?Sized + ser::Serialize,

src/parse.rs

@@ -109,7 +109,7 @@ pub enum AnyNum {
 
 #[derive(Clone, Copy, Debug)]
 pub struct Bytes<'a> {
-    /// Bits set according to the `Extensions` enum.
+    /// Bits set according to the [`Extensions`] enum.
     pub exts: Extensions,
     bytes: &'a [u8],
     cursor: Position,

src/ser/mod.rs

@@ -17,7 +17,10 @@ use crate::{
 mod tests;
 mod value;
 
-/// Serializes `value` into `writer`
+/// Serializes `value` into `writer`.
+///
+/// This function does not generate any newlines or nice formatting;
+/// if you want that, you can use [`to_writer_pretty`] instead.
 pub fn to_writer<W, T>(writer: W, value: &T) -> Result<()>
 where
     W: io::Write,
@@ -38,7 +41,7 @@ where
 /// Serializes `value` and returns it as string.
 ///
 /// This function does not generate any newlines or nice formatting;
-/// if you want that, you can use `to_string_pretty` instead.
+/// if you want that, you can use [`to_string_pretty`] instead.
 pub fn to_string<T>(value: &T) -> Result<String>
 where
     T: ?Sized + Serialize,
@@ -98,7 +101,7 @@ pub struct PrettyConfig {
 }
 
 impl PrettyConfig {
-    /// Creates a default `PrettyConfig`.
+    /// Creates a default [`PrettyConfig`].
     pub fn new() -> Self {
         Default::default()
     }
@@ -229,8 +232,8 @@ impl Default for PrettyConfig {
 
 /// The RON serializer.
 ///
-/// You can just use `to_string` for deserializing a value.
-/// If you want it pretty-printed, take a look at the `pretty` module.
+/// You can just use [`to_string`] for deserializing a value.
+/// If you want it pretty-printed, take a look at [`to_string_pretty`].
 pub struct Serializer<W: io::Write> {
     output: W,
     pretty: Option<(PrettyConfig, Pretty)>,
@@ -241,16 +244,18 @@ pub struct Serializer<W: io::Write> {
 }
 
 impl<W: io::Write> Serializer<W> {
-    /// Creates a new `Serializer`.
+    /// Creates a new [`Serializer`].
     ///
-    /// Most of the time you can just use `to_string` or `to_string_pretty`.
+    /// Most of the time you can just use [`to_string`] or
+    /// [`to_string_pretty`].
     pub fn new(writer: W, config: Option<PrettyConfig>) -> Result<Self> {
         Self::with_options(writer, config, Options::default())
     }
 
-    /// Creates a new `Serializer`.
+    /// Creates a new [`Serializer`].
     ///
-    /// Most of the time you can just use `to_string` or `to_string_pretty`.
+    /// Most of the time you can just use [`to_string`] or
+    /// [`to_string_pretty`].
     pub fn with_options(
         mut writer: W,
         config: Option<PrettyConfig>,

src/value.rs

@@ -14,7 +14,7 @@ use serde::{
 
 use crate::{de::Error, error::Result};
 
-/// A `Value` to `Value` map.
+/// A [`Value`] to [`Value`] map.
 ///
 /// This structure either uses a [BTreeMap](std::collections::BTreeMap) or the
 /// [IndexMap](indexmap::IndexMap) internally.
@@ -25,7 +25,7 @@ use crate::{de::Error, error::Result};
 pub struct Map(MapInner);
 
 impl Map {
-    /// Creates a new, empty `Map`.
+    /// Creates a new, empty [`Map`].
     pub fn new() -> Map {
         Default::default()
     }
@@ -140,20 +140,20 @@ type MapInner = std::collections::BTreeMap<Value, Value>;
 #[cfg(feature = "indexmap")]
 type MapInner = indexmap::IndexMap<Value, Value>;
 
-/// A wrapper for a number, which can be either `f64` or `i64`.
+/// A wrapper for a number, which can be either [`f64`] or [`i64`].
 #[derive(Copy, Clone, Debug, PartialEq, PartialOrd, Eq, Hash, Ord)]
 pub enum Number {
     Integer(i64),
     Float(Float),
 }
 
-/// A wrapper for `f64`, which guarantees that the inner value
-/// is finite and thus implements `Eq`, `Hash` and `Ord`.
+/// A wrapper for [`f64`], which guarantees that the inner value
+/// is finite and thus implements [`Eq`], [`Hash`] and [`Ord`].
 #[derive(Copy, Clone, Debug)]
 pub struct Float(f64);
 
 impl Float {
-    /// Construct a new `Float`.
+    /// Construct a new [`Float`].
     pub fn new(v: f64) -> Self {
         Float(v)
     }
@@ -170,8 +170,8 @@ impl Number {
         v.into()
     }
 
-    /// Returns the `f64` representation of the number regardless of whether the number is stored
-    /// as a float or integer.
+    /// Returns the [`f64`] representation of the [`Number`] regardless of
+    /// whether the number is stored as a float or integer.
     ///
     /// # Example
     ///
@@ -186,7 +186,7 @@ impl Number {
         self.map_to(|i| i as f64, |f| f)
     }
 
-    /// If the `Number` is a float, return it. Otherwise return `None`.
+    /// If the [`Number`] is a float, return it. Otherwise return [`None`].
     ///
     /// # Example
     ///
@@ -201,7 +201,7 @@ impl Number {
         self.map_to(|_| None, Some)
     }
 
-    /// If the `Number` is an integer, return it. Otherwise return `None`.
+    /// If the [`Number`] is an integer, return it. Otherwise return [`None`].
     ///
     /// # Example
     ///
@@ -257,8 +257,9 @@ impl From<i32> for Number {
     }
 }
 
-// The following number conversion checks if the integer fits losslessly into an i64, before
-// constructing a Number::Integer variant. If not, the conversion defaults to float.
+/// The following [`Number`] conversion checks if the integer fits losslessly
+/// into an [`i64`], before constructing a [`Number::Integer`] variant.
+/// If not, the conversion defaults to [`Number::Float`].
 
 impl From<u64> for Number {
     fn from(i: u64) -> Number {
@@ -271,19 +272,19 @@ impl From<u64> for Number {
 }
 
 /// Partial equality comparison
-/// In order to be able to use `Number` as a mapping key, NaN floating values
-/// wrapped in `Float` are equals to each other. It is not the case for
-/// underlying `f64` values itself.
+/// In order to be able to use [`Number`] as a mapping key, NaN floating values
+/// wrapped in [`Float`] are equal to each other. It is not the case for
+/// underlying [`f64`] values itself.
 impl PartialEq for Float {
     fn eq(&self, other: &Self) -> bool {
         self.0.is_nan() && other.0.is_nan() || self.0 == other.0
     }
 }
 
 /// Equality comparison
-/// In order to be able to use `Float` as a mapping key, NaN floating values
-/// wrapped in `Float` are equals to each other. It is not the case for
-/// underlying `f64` values itself.
+/// In order to be able to use [`Float`] as a mapping key, NaN floating values
+/// wrapped in [`Float`] are equal to each other. It is not the case for
+/// underlying [`f64`] values itself.
 impl Eq for Float {}
 
 impl Hash for Float {
@@ -293,9 +294,11 @@ impl Hash for Float {
 }
 
 /// Partial ordering comparison
-/// In order to be able to use `Number` as a mapping key, NaN floating values
-/// wrapped in `Number` are equals to each other and are less then any other
-/// floating value. It is not the case for the underlying `f64` values themselves.
+/// In order to be able to use [`Number`] as a mapping key, NaN floating values
+/// wrapped in [`Number`] are equal to each other and are less then any other
+/// floating value. It is not the case for the underlying [`f64`] values
+/// themselves.
+///
 /// ```
 /// use ron::value::Number;
 /// assert!(Number::new(std::f64::NAN) < Number::new(std::f64::NEG_INFINITY));
@@ -313,10 +316,10 @@ impl PartialOrd for Float {
 }
 
 /// Ordering comparison
-/// In order to be able to use `Float` as a mapping key, NaN floating values
-/// wrapped in `Float` are equals to each other and are less then any other
-/// floating value. It is not the case for underlying `f64` values itself. See
-/// the `PartialEq` implementation.
+/// In order to be able to use [`Float`] as a mapping key, NaN floating values
+/// wrapped in [`Float`] are equal to each other and are less then any other
+/// floating value. It is not the case for underlying [`f64`] values itself.
+/// See the [`PartialEq`] implementation.
 impl Ord for Float {
     fn cmp(&self, other: &Self) -> Ordering {
         self.partial_cmp(other).expect("Bug: Contract violation")
@@ -336,7 +339,7 @@ pub enum Value {
 }
 
 impl Value {
-    /// Tries to deserialize this `Value` into `T`.
+    /// Tries to deserialize this [`Value`] into `T`.
     pub fn into_rust<T>(self) -> Result<T>
     where
         T: DeserializeOwned,
@@ -345,8 +348,8 @@ impl Value {
     }
 }
 
-/// Deserializer implementation for RON `Value`.
-/// This does not support enums (because `Value` doesn't store them).
+/// Deserializer implementation for RON [`Value`].
+/// This does not support enums (because [`Value`] does not store them).
 impl<'de> Deserializer<'de> for Value {
     type Error = Error;