Merge pull request #68 from adrianwn/master

Add code documentation

Author: kraigher

vhdl_lang/src/analysis/lock.rs

@@ -4,28 +4,36 @@
 //
 // Copyright (c) 2019, Olof Kraigher olof.kraigher@gmail.com
 
-///! This module contains structs to handle detecting circular dependencies
-///! during analysis of packages where the dependency tree is not known
+//! This module contains types to handle the analysis data in a thread-safe way,
+//! in particular when the dependencies between design units are not known.
+
 use parking_lot::{MappedRwLockReadGuard, RwLock, RwLockReadGuard, RwLockWriteGuard};
 
+/// Combines an item to be analyzed (typically, a design unit) with the optional results
+/// of that analysis.
 struct AnalysisState<T, R> {
+    /// Data gathered during analysis; `None` while not yet analyzed.
     result: Option<R>,
+
+    /// The subject of analysis; typically, this is a design unit.
     data: T,
 }
 
+/// A thread-safe r/w-lock on an item to be analyzed (`T`) and the analysis results (`R`).
+///
+/// Ensures mutable access during analysis and immutable access after analysis.
 pub struct AnalysisLock<T, R> {
     state: RwLock<AnalysisState<T, R>>,
 }
 
-/// Ensure mutable access during analysis and immutable access after analysis
 impl<T, R> AnalysisLock<T, R> {
     pub fn new(data: T) -> AnalysisLock<T, R> {
         AnalysisLock {
             state: RwLock::new(AnalysisState { result: None, data }),
         }
     }
 
-    /// Get an immutable reference to the data if it is already been analyzed
+    /// Returns an immutable reference to the data and result if it has already been analyzed.
     fn get(&self) -> Option<ReadGuard<T, R>> {
         let guard = self.state.read();
         if guard.result.is_some() {
@@ -35,17 +43,20 @@ impl<T, R> AnalysisLock<T, R> {
         }
     }
 
+    /// Returns an immutable reference to the data.
     pub fn read(&self) -> MappedRwLockReadGuard<'_, T> {
         RwLockReadGuard::map(self.state.read(), |data| &data.data)
     }
 
-    /// Reset analysis state, analysis needs to be redone
+    /// Reset analysis state, analysis needs to be redone.
     pub fn reset(&self) {
         let mut guard = self.state.write();
         guard.result = None;
     }
 
-    /// Get an immmutable reference to the data, assuming it has already been analyzed
+    /// Returns an immmutable reference to the data and result.
+    ///
+    /// Panics if the analysis result is not available.
     pub fn expect_analyzed(&self) -> ReadGuard<T, R> {
         let guard = self.state.read();
 
@@ -56,10 +67,11 @@ impl<T, R> AnalysisLock<T, R> {
         ReadGuard { guard }
     }
 
-    /// Get either:
-    /// - A mutable reference to the data if not analyzed
-    /// - An immmutable reference to the data if already analyzed
-    /// - A Circular dependency error if such is detected
+    /// Creates a view into this lock.
+    ///
+    /// This view provides:
+    /// - a mutable reference to the data if not analyzed
+    /// - an immmutable reference to the data if already analyzed
     pub fn entry(&self) -> AnalysisEntry<T, R> {
         if let Some(guard) = self.get() {
             AnalysisEntry::Occupied(guard)
@@ -80,6 +92,12 @@ impl<T, R> AnalysisLock<T, R> {
     }
 }
 
+/// A view into a thread-safe r/w-lock on an [`AnalysisState`](struct.AnalysisState.html).
+///
+/// Instances of this type are created by
+/// [`AnalysisLock::entry()`](struct.AnalysisLock.html#method.entry)
+/// and allow read-access to a completed analysis data and
+/// read/write-access to incomplete analysis data.
 pub enum AnalysisEntry<'a, T, R> {
     Occupied(ReadGuard<'a, T, R>),
     Vacant(WriteGuard<'a, T, R>),

vhdl_lang/src/analysis/named_entity.rs

@@ -286,14 +286,17 @@ pub struct EntityId {
     id: usize,
 }
 
+/// A named entity as defined in LRM 6.1.
+///
+/// Every declaration creates one or more named entities.
 #[derive(Debug)]
 pub struct NamedEntity {
-    /// An unique id of the entity
-    /// Entities with the same id will be the same
+    /// A unique id of the entity.
+    /// Entities with the same id will be the same.
     id: EntityId,
     implicit: bool,
-    /// The location where the declaration was made
-    /// Builtin and implicit declaration will not have a source position
+    /// The location where the declaration was made.
+    /// Builtin and implicit declaration will not have a source position.
     designator: Designator,
     kind: NamedEntityKind,
     decl_pos: Option<SrcPos>,

vhdl_lang/src/analysis/root.rs

@@ -29,6 +29,9 @@ pub(super) struct AnalysisData {
 }
 
 pub(super) type UnitReadGuard<'a> = ReadGuard<'a, AnyDesignUnit, AnalysisData>;
+
+/// Wraps the AST of a [design unit](../../ast/enum.AnyDesignUnit.html) in a thread-safe
+/// r/w-lock for analysis.
 pub(super) struct LockedUnit {
     ident: Ident,
     unit_id: UnitId,
@@ -69,22 +72,25 @@ impl HasIdent for LockedUnit {
     }
 }
 
+/// Represents a VHDL library containing zero or more design units.
+///
+/// This struct also keeps track of which source file contained which design units.
 struct Library {
     name: Symbol,
 
-    /// Named entity corresponding to the library
+    /// Named entity corresponding to the library.
     ent: Arc<NamedEntity>,
 
     units: FnvHashMap<UnitKey, LockedUnit>,
     units_by_source: FnvHashMap<Source, FnvHashSet<UnitId>>,
 
-    /// Units removed since last analysis
+    /// Units removed since last analysis.
     removed: FnvHashSet<UnitId>,
-    /// Units added since last analysis
+    /// Units added since last analysis.
     added: FnvHashSet<UnitId>,
 
-    /// Design units which were not added since they were duplicates
-    /// They need to be kept for later refresh which might make them not duplicates
+    /// Design units which were not added since they were duplicates.
+    /// They need to be kept for later refresh which might make them not duplicates.
     duplicates: Vec<(SrcPos, LockedUnit)>,
 }
 
@@ -140,7 +146,7 @@ impl<'a> Library {
         }
     }
 
-    /// Refresh library after removing or adding new design units
+    /// Refresh library after removing or adding new design units.
     fn refresh(&mut self, diagnostics: &mut dyn DiagnosticHandler) {
         self.append_duplicate_diagnostics(diagnostics);
     }
@@ -178,8 +184,8 @@ impl<'a> Library {
         }
     }
 
-    /// Remove all design units defined in source
-    /// This is used for incremental analysis where only a single source file is updated
+    /// Remove all design units defined in source.
+    /// This is used for incremental analysis where only a single source file is updated.
     fn remove_source(&mut self, source: &Source) {
         let removed = &mut self.removed;
         self.units.retain(|_, value| {
@@ -207,8 +213,8 @@ impl<'a> Library {
         }
     }
 
-    /// Iterate over units in the order they appear in the file
-    /// Ensures diagnostics does not have to be sorted later
+    /// Iterate over units in the order they appear in the file.
+    /// Ensures diagnostics do not have to be sorted later.
     fn sorted_unit_ids(&self) -> Vec<UnitId> {
         // @TODO insert sort when adding instead
         let mut result = Vec::new();
@@ -230,18 +236,23 @@ impl<'a> Library {
     }
 }
 
+/// Contains the entire design state.
+///
+/// Besides all loaded libraries and design units, `DesignRoot` also keeps track of
+/// dependencies between design units.
 pub struct DesignRoot {
     symbols: Arc<Symbols>,
     libraries: FnvHashMap<Symbol, Library>,
 
-    // Dependency tracking for incremental analysis
-    // user => set(users)
+    // Dependency tracking for incremental analysis.
+    // user  =>  set(users)
     users_of: RwLock<FnvHashMap<UnitId, FnvHashSet<UnitId>>>,
 
-    // missing primary name  => set(affected)
+    // missing primary name  =>  set(affected)
     missing_primary: RwLock<FnvHashMap<(Symbol, Symbol), FnvHashSet<UnitId>>>,
 
-    // library name  => set(affected)
+    // Tracks which units have a "use library.all;" clause.
+    // library name  =>  set(affected)
     users_of_library_all: RwLock<FnvHashMap<Symbol, FnvHashSet<UnitId>>>,
 }
 
@@ -466,7 +477,8 @@ impl DesignRoot {
         }
     }
 
-    /// Reset all unit that need to be re-analyzed
+    /// Resets the analysis state of all design units which need to be re-analyzed
+    /// because another design unit has been added or removed.
     fn reset(&mut self) {
         let mut removed = FnvHashSet::default();
         let mut added = FnvHashSet::default();

vhdl_lang/src/ast.rs

@@ -249,6 +249,7 @@ pub enum Expression {
     New(Box<WithPos<Allocator>>),
 }
 
+/// An identifier together with the lexical source location it occurs in.
 pub type Ident = WithPos<Symbol>;
 
 #[derive(PartialEq, Debug, Clone, Copy)]

vhdl_lang/src/ast/any_design_unit.rs

@@ -27,13 +27,18 @@ pub enum AnyKind {
     Secondary(SecondaryKind),
 }
 
-/// Without Kind to get name conflict between different primary units
+/// Stores a design unit's name and, for secondary units,
+/// the name of its associated primary unit.
 #[derive(PartialEq, Eq, Hash, Clone, Debug)]
 pub enum UnitKey {
     Primary(Symbol),
     Secondary(Symbol, Symbol),
 }
 
+/// Identifies a design unit.
+///
+/// Additionally, a `UnitId` specifies a unit's name, kind, library,
+/// and, for secondary units, its associated primary unit.
 #[derive(PartialEq, Eq, Hash, Clone, Debug)]
 pub struct UnitId {
     library_name: Symbol,
@@ -71,6 +76,8 @@ impl UnitId {
         &self.library_name
     }
 
+    /// For a secondary unit, returns the name of the associated primary unit;
+    /// for a primary unit, returns its own name.
     pub fn primary_name(&self) -> &Symbol {
         match self.key {
             UnitKey::Primary(ref name) => name,

vhdl_lang/src/data/source.rs

@@ -20,7 +20,8 @@ use std::sync::Arc;
 
 struct FileId {
     name: PathBuf,
-    hash: u64, // Hash of name
+    /// Hash value of `self.name`.
+    hash: u64,
 }
 
 impl FileId {
@@ -50,13 +51,14 @@ fn hash(value: &Path) -> u64 {
     hasher.finish()
 }
 
+/// Represents a single source file and its contents.
 struct UniqueSource {
     file_id: FileId,
     contents: RwLock<Contents>,
 }
 
 impl fmt::Debug for UniqueSource {
-    /// Custom implementation to avoid large contents strings
+    /// Custom implementation to avoid large contents strings.
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "Source {{file_name: {:?}}}", self.file_name())
     }
@@ -96,6 +98,8 @@ impl UniqueSource {
     }
 }
 
+/// A thread-safe reference to a source file.
+/// Multiple objects of this type can refer to the same source.
 #[derive(Debug, Clone)]
 pub struct Source {
     source: Arc<UniqueSource>,
@@ -116,6 +120,10 @@ impl Hash for Source {
 }
 
 impl Source {
+    /// Creates a source from a (virtual) name and in-memory contents.
+    ///
+    /// Note: For differing values of `contents`, the value of `file_name`
+    /// *must* differ as well.
     pub fn inline(file_name: &Path, contents: &str) -> Source {
         Source {
             source: Arc::new(UniqueSource::inline(file_name, contents)),
@@ -160,9 +168,12 @@ impl Source {
     }
 }
 
+/// A lexical position (line, column) in a source.
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Hash, Debug)]
 pub struct Position {
+    /// Line (zero-based).
     pub line: u32,
+    /// Column (zero-based).
     pub character: u32,
 }
 
@@ -211,9 +222,12 @@ impl Position {
     }
 }
 
+/// A lexical range in a source.
 #[derive(PartialEq, Eq, Clone, Copy, Hash, Debug)]
 pub struct Range {
+    /// Start of the range (inclusive).
     pub start: Position,
+    /// End of the range (exclusive).
     pub end: Position,
 }
 
@@ -223,14 +237,15 @@ impl Range {
     }
 }
 
-/// Lexical position in a file.
+/// A lexical range within a specific source file.
 #[derive(PartialEq, Clone, Debug, Eq, Hash)]
 pub struct SrcPos {
-    /// The source
+    /// The referenced source file.
     pub source: Source,
     range: Range,
 }
 
+/// A generic object with an associated source file and lexical range.
 #[derive(PartialEq, Clone, Debug)]
 pub struct WithPos<T> {
     pub item: T,
@@ -261,6 +276,7 @@ impl<T> WithPos<T> {
             pos: self.pos,
         }
     }
+
     pub fn try_map_into<F, U>(self, f: F) -> DiagnosticResult<WithPos<U>>
     where
         F: FnOnce(T) -> Result<U, String>,
@@ -422,7 +438,7 @@ impl SrcPos {
         (lineno_len, result)
     }
 
-    /// Create a string for pretty printing
+    /// Create a string for pretty printing.
     pub fn code_context(&self) -> String {
         self.lineno_len_and_code_context().1
     }
@@ -457,8 +473,8 @@ impl SrcPos {
         result
     }
 
-    /// Combines two lexical positions into a larger legical position overlapping both
-    /// The file name is assumed to be the same
+    /// Combines two lexical positions into a larger lexical position overlapping both.
+    /// The file name is assumed to be the same.
     pub fn combine_into(self, other: &dyn AsRef<Self>) -> Self {
         let other = other.as_ref();
         debug_assert!(self.source == other.source, "Assumes sources are equal");
@@ -493,6 +509,10 @@ impl SrcPos {
     }
 }
 
+/// Denotes an item with an associated source file.
+///
+/// Most types that implement this trait do so through the blanket implementation
+/// on [`HasSrcPos`](trait.HasSrcPos.html).
 pub trait HasSource {
     fn source(&self) -> &Source;
 }
@@ -503,6 +523,7 @@ impl HasSource for Source {
     }
 }
 
+/// Denotes an item with an associated lexical range in a source file.
 pub trait HasSrcPos {
     fn pos(&self) -> &SrcPos;
 }