Warn for missing docs of public types

src/common.rs

@@ -814,6 +814,7 @@ impl<'b> fmt::LowerHex for ParseBuffer<'b> {
 
 /// Value of an enumerate type.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
+#[allow(missing_docs)]
 pub enum Variant {
     U8(u8),
     U16(u16),

src/dbi.rs

@@ -104,6 +104,7 @@ impl<'s> DebugInformation<'s> {
 ///
 /// This version type is used in multiple locations: the DBI header, and the PDBI header.
 #[derive(Debug, Copy, Clone)]
+#[allow(missing_docs)]
 pub enum HeaderVersion {
     V41,
     V50,
@@ -114,13 +115,14 @@ pub enum HeaderVersion {
 }
 
 impl From<u32> for HeaderVersion {
+    #[allow(clippy::inconsistent_digit_grouping)]
     fn from(v: u32) -> Self {
         match v {
-            930_803 => HeaderVersion::V41,
-            19_960_307 => HeaderVersion::V50,
-            19_970_606 => HeaderVersion::V60,
-            19_990_903 => HeaderVersion::V70,
-            20_091_201 => HeaderVersion::V110,
+            93_08_03 => HeaderVersion::V41,
+            1996_03_07 => HeaderVersion::V50,
+            1997_06_06 => HeaderVersion::V60,
+            1999_09_03 => HeaderVersion::V70,
+            2009_12_01 => HeaderVersion::V110,
             _ => HeaderVersion::OtherValue(v),
         }
     }

src/lib.rs

@@ -44,6 +44,8 @@
 //! # assert!(test().expect("test") > 2000);
 //! ```
 
+#![warn(missing_docs)]
+
 // modules
 mod common;
 mod dbi;

src/modi/mod.rs

@@ -95,6 +95,7 @@ impl<'s> ModuleInfo<'s> {
 
 /// Checksum of a source file's contents.
 #[derive(Clone, Debug)]
+#[allow(missing_docs)]
 pub enum FileChecksum<'a> {
     None,
     Md5(&'a [u8]),

src/symbol/annotations.rs

@@ -67,18 +67,43 @@ impl BinaryAnnotationOpcode {
 /// evaluate the state changes for inline information.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub enum BinaryAnnotation {
+    /// Sets the code offset to the given absolute value.
     CodeOffset(u32),
+    /// Sets the base for all code offsets to the given absolute value. All following code offsets
+    /// are relative to this base value.
     ChangeCodeOffsetBase(u32),
+    /// **Emitting**. Advances the code offset by the given value.
+    ///
+    /// This annotation emits a line record. The length of the covered code block can be established
+    /// by a following `ChangeCodeLength` annotation, or by the offset of the next emitted record.
     ChangeCodeOffset(u32),
+    /// Adjusts the code length of the previously emitted line record. The code length resets with
+    /// every line record.
     ChangeCodeLength(u32),
+    /// Sets the file index of following line records.
     ChangeFile(FileIndex),
+    /// Advances the line number by the given value.
     ChangeLineOffset(i32),
+    /// Sets the number of source lines covered by following line records. Defaults to `1`.
     ChangeLineEndDelta(u32),
+    /// Sets the kind of the line record. Defaults to `Statement`.
     ChangeRangeKind(u32),
+    /// Sets the start column number. Defaults to `None`.
     ChangeColumnStart(u32),
+    /// Advances the end column number by the given value.
     ChangeColumnEndDelta(i32),
+    /// **Emitting**. Advances the code offset and the line number by the given values.
+    ///
+    /// This annotation emits a line record. The length of the covered code block can be established
+    /// by a following `ChangeCodeLength` annotation, or by the offset of the next emitted record.
     ChangeCodeOffsetAndLineOffset(u32, i32),
+    /// **Emitting**. Sets the code length and advances the code offset by the given value.
+    ///
+    /// This annotation emits a line record that is valid for the given code length. This is usually
+    /// issued as one of the last annotations, as there is no subsequent line record to derive the
+    /// code length from.
     ChangeCodeLengthAndCodeOffset(u32, u32),
+    /// Sets the end column number.
     ChangeColumnEnd(u32),
 }
 

src/tpi/data.rs

@@ -5,6 +5,8 @@
 // http://opensource.org/licenses/MIT>, at your option. This file may not be
 // copied, modified, or distributed except according to those terms.
 
+#![allow(missing_docs)]
+
 use crate::common::*;
 use crate::tpi::constants::*;
 use crate::tpi::primitive::*;
@@ -668,11 +670,11 @@ pub enum PointerKind {
     BaseType,
     /// Based on self.
     BaseSelf,
-    /// 32 bit pointer.
+    /// 32-bit pointer.
     Near32,
-    /// 16:32 pointer.
+    /// 48-bit 16:32 pointer.
     Far32,
-    /// 64 bit pointer.
+    /// 64-bit pointer.
     Ptr64,
 }
 

src/tpi/id.rs

@@ -23,11 +23,17 @@ fn parse_string<'t>(leaf: u16, buf: &mut ParseBuffer<'t>) -> Result<RawString<'t
 /// Encapsulates parsed data about an `Id`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum IdData<'t> {
+    /// Global function, usually inlined.
     Function(FunctionId<'t>),
+    /// Member function, usually inlined.
     MemberFunction(MemberFunctionId<'t>),
+    /// Tool, version and command line build information.
     BuildInfo(BuildInfoId),
+    /// A list of substrings.
     StringList(StringListId),
+    /// A string.
     String(StringId<'t>),
+    /// Source and line of the definition of a User Defined Type (UDT).
     UserDefinedTypeSource(UserDefinedTypeSourceId),
 }
 
@@ -93,6 +99,9 @@ impl<'t> TryFromCtx<'t, scroll::Endian> for IdData<'t> {
     }
 }
 
+/// Global function, usually inlined.
+///
+/// This Id is usually referenced by [`InlineSiteSymbol`](struct.InlineSiteSymbol.html).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct FunctionId<'t> {
     /// Parent scope of this id.
@@ -103,6 +112,9 @@ pub struct FunctionId<'t> {
     pub name: RawString<'t>,
 }
 
+/// Member function, usually inlined.
+///
+/// This Id is usually referenced by [`InlineSiteSymbol`](struct.InlineSiteSymbol.html).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct MemberFunctionId<'t> {
     /// Index of the parent type.
@@ -113,18 +125,28 @@ pub struct MemberFunctionId<'t> {
     pub name: RawString<'t>,
 }
 
+/// Tool, version and command line build information.
+///
+/// This Id is usually referenced by [`BuildInfoSymbol`](struct.BuildInfoSymbol.html).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct BuildInfoId {
     /// Indexes of build arguments.
     pub arguments: Vec<IdIndex>,
 }
 
+/// A list of substrings.
+///
+/// This Id is usually referenced by [`StringId`](struct.StringId.html).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct StringListId {
     /// The list of substrings.
     pub substrings: Vec<TypeIndex>,
 }
 
+/// A string.
+///
+/// This Id is usually referenced by [`FunctionId`](struct.FunctionId.html) and contains the
+/// full namespace of a function.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct StringId<'t> {
     /// Index of the list of substrings.
@@ -133,6 +155,7 @@ pub struct StringId<'t> {
     pub name: RawString<'t>,
 }
 
+/// Source and line of the definition of a User Defined Type (UDT).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct UserDefinedTypeSourceId {
     /// Index of the UDT's type definition.

src/tpi/primitive.rs

@@ -25,12 +25,14 @@ use crate::tpi::data::TypeData;
 /// Represents a primitive type like `void` or `char *`.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 pub struct PrimitiveType {
+    /// The kind of the primitive type.
     pub kind: PrimitiveKind,
 
-    /// What kind of indirection was applied to the underlying type
+    /// What kind of indirection was applied to the underlying type.
     pub indirection: Indirection,
 }
 
+/// A simple type.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 pub enum PrimitiveKind {
     /// Void type