From c1b126d6e8628e9cfb947ea855bf6708d93cd028 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20M=C3=BCller?= Date: Mon, 11 Sep 2023 15:53:15 -0700 Subject: [PATCH] Warn on `missing_docs` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- include/blazesym.h | 25 +++++++++++++++++++++++++ src/c_api/inspect.rs | 6 ++++++ src/c_api/normalize.rs | 1 + src/c_api/symbolize.rs | 2 ++ src/error.rs | 10 +++++++++- src/lib.rs | 7 ++++++- src/normalize/meta.rs | 3 +++ src/symbolize/source.rs | 1 + 8 files changed, 53 insertions(+), 2 deletions(-) diff --git a/include/blazesym.h b/include/blazesym.h index b6b53ba1..c55a5aa0 100644 --- a/include/blazesym.h +++ b/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; diff --git a/src/c_api/inspect.rs b/src/c_api/inspect.rs index aa5193a0..33678987 100644 --- a/src/c_api/inspect.rs +++ b/src/c_api/inspect.rs @@ -113,11 +113,17 @@ impl From 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, } diff --git a/src/c_api/normalize.rs b/src/c_api/normalize.rs index da5c3790..5907c97f 100644 --- a/src/c_api/normalize.rs +++ b/src/c_api/normalize.rs @@ -227,6 +227,7 @@ impl From for Elf { #[repr(C)] #[derive(Debug)] pub struct blaze_user_addr_meta_unknown { + /// This member is unused. pub _unused: u8, } diff --git a/src/c_api/symbolize.rs b/src/c_api/symbolize.rs index d5a8ac36..d884c357 100644 --- a/src/c_api/symbolize.rs +++ b/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, } diff --git a/src/error.rs b/src/error.rs index 60800cda..d9637a64 100644 --- a/src/error.rs +++ b/src/error.rs @@ -438,6 +438,7 @@ impl From 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: private::Sealed where Self: Sized, { + /// Unwrap `self` into an `Ok` or an [`Error`] of the given kind. fn ok_or_error(self, kind: io::ErrorKind, f: F) -> Result 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(self, f: F) -> Result 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(self, f: F) -> Result 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(self, f: F) -> Result where @@ -592,7 +600,7 @@ impl IntoError for Option { 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())) } } diff --git a/src/lib.rs b/src/lib.rs index 12c93a3f..347e46d2 100644 --- a/src/lib.rs +++ b/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; diff --git a/src/normalize/meta.rs b/src/normalize/meta.rs index 91edc987..cc49fc23 100644 --- a/src/normalize/meta.rs +++ b/src/normalize/meta.rs @@ -81,8 +81,11 @@ impl From 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), } diff --git a/src/symbolize/source.rs b/src/symbolize/source.rs index 9aeb9748..706d5561 100644 --- a/src/symbolize/source.rs +++ b/src/symbolize/source.rs @@ -126,6 +126,7 @@ impl From for Source<'static> { } +/// Enumeration of supported Gsym sources. #[derive(Clone, Debug)] pub enum Gsym<'dat> { /// "Raw" Gsym data.