From 28a71b826e85bc20ba61170fe258a124a154deec Mon Sep 17 00:00:00 2001 From: maxrdz Date: Wed, 21 Feb 2024 20:30:28 -0700 Subject: [PATCH] rustdocs: Wrote module-level docstrings to summarize components --- libdonet/src/datagram.rs | 3 +++ libdonet/src/dcarray.rs | 3 +++ libdonet/src/dcatomic.rs | 3 +++ libdonet/src/dcfield.rs | 5 ++++- libdonet/src/dcfile.rs | 17 +++++++++++------ libdonet/src/dckeyword.rs | 3 +++ libdonet/src/dclass.rs | 3 +++ libdonet/src/dclexer.rs | 3 +++ libdonet/src/dcmolecular.rs | 3 +++ libdonet/src/dcnumeric.rs | 10 ++++++---- libdonet/src/dcparameter.rs | 3 +++ libdonet/src/dcparser.rs | 3 +++ libdonet/src/dcstruct.rs | 2 ++ libdonet/src/dctype.rs | 3 +++ 14 files changed, 53 insertions(+), 11 deletions(-) diff --git a/libdonet/src/datagram.rs b/libdonet/src/datagram.rs index 918723e..6f8cf36 100644 --- a/libdonet/src/datagram.rs +++ b/libdonet/src/datagram.rs @@ -15,6 +15,9 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Provides structures to write network datagrams and tools +//! for iterating over datagram data. + use crate::byte_order as endianness; use crate::globals; use std::mem; diff --git a/libdonet/src/dcarray.rs b/libdonet/src/dcarray.rs index 4f87c74..ab6763d 100644 --- a/libdonet/src/dcarray.rs +++ b/libdonet/src/dcarray.rs @@ -15,6 +15,9 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Data model of the DC Array element, which is a parameter +//! type that stores a list of values of the same data type. + use crate::dcnumeric::DCNumericRange; use crate::dctype::{DCTypeDefinition, DCTypeDefinitionInterface, DCTypeEnum}; use crate::hashgen::DCHashGenerator; diff --git a/libdonet/src/dcatomic.rs b/libdonet/src/dcatomic.rs index 5f9e441..8cf263e 100644 --- a/libdonet/src/dcatomic.rs +++ b/libdonet/src/dcatomic.rs @@ -15,6 +15,9 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Data model for a DC Atomic Field, which represents a remote +//! procedure call method of a Distributed Class. + use crate::dcfield::{DCField, DCFieldInterface}; use crate::dclass::DClass; use crate::dcparameter::DCParameter; diff --git a/libdonet/src/dcfield.rs b/libdonet/src/dcfield.rs index 761894a..bc0a51c 100644 --- a/libdonet/src/dcfield.rs +++ b/libdonet/src/dcfield.rs @@ -15,6 +15,9 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Base data model for DC Field elements. Alone, it represents +//! an attribute of a structure or Distributed Class. + use crate::datagram::Datagram; use crate::dcatomic::DCAtomicField; use crate::dckeyword::{DCKeywordList, DCKeywordListInterface, IdentifyKeyword}; @@ -92,9 +95,9 @@ pub trait DCFieldInterface { fn has_default_value(&self) -> bool; fn validate_ranges(&self, packed_data: &Datagram) -> bool; + fn is_bogus_field(&self) -> bool; // Inline functions for Panda historical keywords - fn is_bogus_field(&self) -> bool; fn is_required(&self) -> bool; fn is_broadcast(&self) -> bool; fn is_ram(&self) -> bool; diff --git a/libdonet/src/dcfile.rs b/libdonet/src/dcfile.rs index f2e6e03..48c3faf 100644 --- a/libdonet/src/dcfile.rs +++ b/libdonet/src/dcfile.rs @@ -15,6 +15,9 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Root structure that stores the collection of DC elements +//! in memory. Provides functions for manipulating the tree. + use crate::dckeyword::DCKeyword; use crate::dclass::DClass; use crate::dcstruct::DCStruct; @@ -38,6 +41,9 @@ impl DCImport { } } +/// Data model that provides a high level representation of a single, +/// or collection, of DC files and their elements such as class imports, +/// type definitions, structures, and Distributed Classes. #[derive(Debug)] pub struct DCFile { structs: Vec>, @@ -100,17 +106,16 @@ impl DCFile { } impl DCFileInterface for DCFile { - /* Returns a 32-bit hash index associated with this file. This number is - * guaranteed to be consistent if the contents of the file have not changed, - * and it is very likely to be different if the contents of the file do change. - */ + /// Returns a 32-bit hash index associated with this file. This number is + /// guaranteed to be consistent if the contents of the file have not changed, + /// and it is very likely to be different if the contents of the file do change. fn get_hash(&mut self) -> globals::DCFileHash { let mut hashgen: DCHashGenerator = DCHashGenerator::new(); self.generate_hash(&mut hashgen); hashgen.get_hash() } - // Accumulates the elements of the DC file into the hash. + /// Accumulates the elements of the DC file into the hash. fn generate_hash(&mut self, hashgen: &mut DCHashGenerator) { if globals::DC_VIRTUAL_INHERITANCE { // Just to change the hash output in this case. @@ -128,7 +133,7 @@ impl DCFileInterface for DCFile { } } - // Returns a string with the hash as a pretty format hexadecimal. + /// Returns a string with the hash as a pretty format hexadecimal. fn get_pretty_hash(&mut self) -> String { format!("0x{:0width$x}", self.get_hash(), width = 8) // 2 hex / byte = 8 hex } diff --git a/libdonet/src/dckeyword.rs b/libdonet/src/dckeyword.rs index c321984..c6c7915 100644 --- a/libdonet/src/dckeyword.rs +++ b/libdonet/src/dckeyword.rs @@ -15,6 +15,9 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Representation of arbitrary and historical +//! keywords as defined in the DC file. + use crate::hashgen::DCHashGenerator; use multimap::MultiMap; use std::ops::Deref; diff --git a/libdonet/src/dclass.rs b/libdonet/src/dclass.rs index 059e2ae..7bca258 100644 --- a/libdonet/src/dclass.rs +++ b/libdonet/src/dclass.rs @@ -15,6 +15,9 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Data model for Distributed Class definitions in the DC file. +//! Stores DC Fields and tracks class hierarchy. + use crate::dcatomic::{DCAtomicField, DCAtomicFieldInterface}; use crate::dcfield::{ClassField, DCFieldInterface}; use crate::globals; diff --git a/libdonet/src/dclexer.rs b/libdonet/src/dclexer.rs index 812339f..24ab622 100644 --- a/libdonet/src/dclexer.rs +++ b/libdonet/src/dclexer.rs @@ -15,6 +15,9 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Definition of the Lexer machine to process raw DC file +//! string data into a stream of lexical tokens for the DC parser. + use crate::globals::{DC_VIEW_SUFFIXES, HISTORICAL_DC_KEYWORDS}; use plex::lexer; diff --git a/libdonet/src/dcmolecular.rs b/libdonet/src/dcmolecular.rs index 57805e0..e83f7f7 100644 --- a/libdonet/src/dcmolecular.rs +++ b/libdonet/src/dcmolecular.rs @@ -15,6 +15,9 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Data model for a DC Molecular field, which represents +//! a form of a field 'alias' for a collection of fields. + use crate::dcfield::DCField; #[derive(Debug)] diff --git a/libdonet/src/dcnumeric.rs b/libdonet/src/dcnumeric.rs index e61d53f..3e77d64 100644 --- a/libdonet/src/dcnumeric.rs +++ b/libdonet/src/dcnumeric.rs @@ -15,15 +15,17 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Structure representing data types supported in the DC +//! language and enforcing numeric limits through constraints. + use crate::datagram::{Datagram, DatagramIterator}; use crate::dctype::*; use crate::hashgen::DCHashGenerator; use std::mem::size_of; -/* Numeric Range structs are used to represent a range of signed/unsigned - * integers or floating point numbers. Used for enforcing numeric limits - * withing constraints of array, string, or blob sized types. - */ +/// Numeric Range structs are used to represent a range of signed/unsigned +/// integers or floating point numbers. Used for enforcing numeric limits +/// within constraints of array, string, or blob sized types. #[derive(Clone)] pub struct DCNumericRange { range_type: DCNumberType, diff --git a/libdonet/src/dcparameter.rs b/libdonet/src/dcparameter.rs index d76c558..fb74332 100644 --- a/libdonet/src/dcparameter.rs +++ b/libdonet/src/dcparameter.rs @@ -15,5 +15,8 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Data model that represents a single parameter of an atomic +//! field, which together form a RPC method signature. + #[derive(Debug)] pub struct DCParameter {} diff --git a/libdonet/src/dcparser.rs b/libdonet/src/dcparser.rs index bac47ca..2ee4905 100644 --- a/libdonet/src/dcparser.rs +++ b/libdonet/src/dcparser.rs @@ -15,6 +15,9 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Definition of the DC language context free grammar for the +//! LALR(1) parser processing the stream of lexical tokens. + /* The following suppress linting warnings, which are okay to ignore * as they go off in the parser grammar definitions, which we are writing * just as the plex crate readme says we should, so everything is okay. diff --git a/libdonet/src/dcstruct.rs b/libdonet/src/dcstruct.rs index 1d6a42b..a67d0f7 100644 --- a/libdonet/src/dcstruct.rs +++ b/libdonet/src/dcstruct.rs @@ -15,6 +15,8 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Data model representing a DC Struct element. + #[derive(Debug, Default, PartialEq)] pub struct DCStruct {} diff --git a/libdonet/src/dctype.rs b/libdonet/src/dctype.rs index 2d977ff..1a7e9fd 100644 --- a/libdonet/src/dctype.rs +++ b/libdonet/src/dctype.rs @@ -15,6 +15,9 @@ // along with this program; if not, write to the Free Software Foundation, // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +//! Represents all data types supported by the DC language +//! and developer-defined type alias definitions. + use crate::globals::DgSizeTag; use crate::hashgen::DCHashGenerator; use strum_macros::EnumIs;