Warn on missing_docs

We try to have reasonably comprehensive documentation for public parts
of the API surface. The compiler can help with that task by warning when
such documentation is missing.
Enable the corresponding lint to make it do just that and add
documentation for everything flagged.

Signed-off-by: Daniel Müller <[email protected]>

include/blazesym.h

@@ -74,11 +74,29 @@ typedef struct blaze_symbolizer blaze_symbolizer;
  * Information about a looked up symbol.
  */
 typedef struct blaze_sym_info {
+  /**
+   * See [`inspect::SymInfo::name`].
+   */
   const char *name;
+  /**
+   * See [`inspect::SymInfo::addr`].
+   */
   uintptr_t addr;
+  /**
+   * See [`inspect::SymInfo::size`].
+   */
   size_t size;
+  /**
+   * See [`inspect::SymInfo::file_offset`].
+   */
   uint64_t file_offset;
+  /**
+   * See [`inspect::SymInfo::obj_file_name`].
+   */
   const char *obj_file_name;
+  /**
+   * See [`inspect::SymInfo::sym_type`].
+   */
   enum blaze_sym_type sym_type;
 } blaze_sym_info;
 
@@ -144,6 +162,9 @@ typedef struct blaze_user_addr_meta_elf {
  * C compatible version of [`Unknown`].
  */
 typedef struct blaze_user_addr_meta_unknown {
+  /**
+   * This member is unused.
+   */
   uint8_t _unused;
 } blaze_user_addr_meta_unknown;
 
@@ -299,6 +320,10 @@ typedef struct blaze_sym {
    * code.
    */
   uint32_t line;
+  /**
+   * The column number of the symbolized instruction in the source
+   * code.
+   */
   uint16_t column;
 } blaze_sym;
 

src/c_api/inspect.rs

@@ -113,11 +113,17 @@ impl From<SymType> for blaze_sym_type {
 #[repr(C)]
 #[derive(Debug)]
 pub struct blaze_sym_info {
+    /// See [`inspect::SymInfo::name`].
     pub name: *const c_char,
+    /// See [`inspect::SymInfo::addr`].
     pub addr: Addr,
+    /// See [`inspect::SymInfo::size`].
     pub size: usize,
+    /// See [`inspect::SymInfo::file_offset`].
     pub file_offset: u64,
+    /// See [`inspect::SymInfo::obj_file_name`].
     pub obj_file_name: *const c_char,
+    /// See [`inspect::SymInfo::sym_type`].
     pub sym_type: blaze_sym_type,
 }
 

src/c_api/normalize.rs

@@ -227,6 +227,7 @@ impl From<blaze_user_addr_meta_elf> for Elf {
 #[repr(C)]
 #[derive(Debug)]
 pub struct blaze_user_addr_meta_unknown {
+    /// This member is unused.
     pub _unused: u8,
 }
 

src/c_api/symbolize.rs

@@ -198,6 +198,8 @@ pub struct blaze_sym {
     /// The line number on which the symbol is located in the source
     /// code.
     pub line: u32,
+    /// The column number of the symbolized instruction in the source
+    /// code.
     pub column: u16,
 }
 

src/error.rs

@@ -438,6 +438,7 @@ impl From<io::Error> for Error {
     }
 }
 
+
 /// A trait providing ergonomic chaining capabilities to [`Error`].
 pub trait ErrorExt: private::Sealed {
     /// The output type produced by [`context`](Self::context) and
@@ -552,11 +553,14 @@ pub trait IntoError<T>: private::Sealed
 where
     Self: Sized,
 {
+    /// Unwrap `self` into an `Ok` or an [`Error`] of the given kind.
     fn ok_or_error<C, F>(self, kind: io::ErrorKind, f: F) -> Result<T, Error>
     where
         C: ToString,
         F: FnOnce() -> C;
 
+    /// Unwrap `self` into an `Ok` or an [`Error`] of the
+    /// [`ErrorKind::InvalidData`] kind.
     #[inline]
     fn ok_or_invalid_data<C, F>(self, f: F) -> Result<T, Error>
     where
@@ -566,6 +570,8 @@ where
         self.ok_or_error(io::ErrorKind::InvalidData, f)
     }
 
+    /// Unwrap `self` into an `Ok` or an [`Error`] of the
+    /// [`ErrorKind::InvalidInput`] kind.
     #[inline]
     fn ok_or_invalid_input<C, F>(self, f: F) -> Result<T, Error>
     where
@@ -575,6 +581,8 @@ where
         self.ok_or_error(io::ErrorKind::InvalidInput, f)
     }
 
+    /// Unwrap `self` into an `Ok` or an [`Error`] of the
+    /// [`ErrorKind::UnexpectedEof`] kind.
     #[inline]
     fn ok_or_unexpected_eof<C, F>(self, f: F) -> Result<T, Error>
     where
@@ -592,7 +600,7 @@ impl<T> IntoError<T> for Option<T> {
         C: ToString,
         F: FnOnce() -> C,
     {
-        self.ok_or_else(|| Error::with_io_error(kind, f().to_string()))
+        self.ok_or_else(|| Error::with_io_error(kind, f()))
     }
 }
 

src/lib.rs

@@ -23,10 +23,15 @@
 
 #![allow(clippy::collapsible_if, clippy::let_and_return, clippy::let_unit_value)]
 #![deny(unsafe_op_in_unsafe_fn)]
-#![warn(missing_debug_implementations)]
+#![warn(
+    missing_debug_implementations,
+    missing_docs,
+    rustdoc::broken_intra_doc_links
+)]
 #![cfg_attr(feature = "nightly", feature(test))]
 #![cfg_attr(not(feature = "lru"), allow(dead_code))]
 
+
 #[cfg(feature = "nightly")]
 extern crate test;
 

src/normalize/meta.rs

@@ -81,8 +81,11 @@ impl From<Unknown> for UserAddrMeta {
 #[derive(Clone, Debug, PartialEq)]
 #[non_exhaustive]
 pub enum UserAddrMeta {
+    /// The address belongs to an ELF file residing in an APK.
     ApkElf(ApkElf),
+    /// The address belongs to an ELF file.
     Elf(Elf),
+    /// The address' origin is unknown.
     Unknown(Unknown),
 }
 

src/symbolize/source.rs

@@ -126,6 +126,7 @@ impl From<Process> for Source<'static> {
 }
 
 
+/// Enumeration of supported Gsym sources.
 #[derive(Clone, Debug)]
 pub enum Gsym<'dat> {
     /// "Raw" Gsym data.