Commentary: Cleanup all include/* header comments.

include/verilated.cpp

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2003-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,15 +12,15 @@
 //=========================================================================
 ///
 /// \file
-/// \brief Verilator: Linked against all applications using Verilated source.
+/// \brief Verilated general routine implementation code
 ///
-///     This file must be compiled and linked against all objects
+/// This file must be compiled and linked against all Verilated objects
-///     created from Verilator.
+/// (all code created from Verilator).
 ///
-///     Those macro/function/variable starting or ending in _ are internal,
+/// Verilator always adds this file to the Makefile for the linker.
-///     however many of the other function/macros here are also internal.
 ///
-/// Code available from: https://verilator.org
+/// Those macro/function/variable starting or ending in _ are internal,
+/// however many of the other function/macros here are also internal.
 ///
 //=========================================================================
 // Internal note:

include/verilated.h

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2003-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,21 +12,23 @@
 //*************************************************************************
 ///
 /// \file
-/// \brief Verilator: Common include for all Verilated C files
+/// \brief Verilated common header, include for all Verilated C files
 ///
-///     This file is included automatically by Verilator at the top of
+/// This file is included automatically by Verilator at the top of all C++
-///     all C++ files it generates.  It contains standard macros and
+/// files it generates.  It contains standard macros and classes required
-///     classes required by the Verilated code.
+/// by the Verilated code.
 ///
-///     Those macro/function/variable starting or ending in _ are internal,
+/// User wrapper code may need to include this to get appropriate
-///     however many of the other function/macros here are also internal.
+/// structures, however they would generally just include the
+/// Verilated-model's header instead (which then includes this).
 ///
-/// Code available from: https://verilator.org
+/// Those macro/function/variable starting or ending in _ are internal,
+/// however many of the other function/macros here are also internal.
 ///
 //*************************************************************************
 
 #ifndef VERILATOR_VERILATED_H_
-#define VERILATOR_VERILATED_H_  ///< Header Guard
+#define VERILATOR_VERILATED_H_
 
 // clang-format off
 #include "verilatedos.h"

include/verilated.v

@@ -2,8 +2,6 @@
 //
 // Code available from: https://verilator.org
 //
-//*************************************************************************
-//
 // Copyright 2003-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License

include/verilated_config.h.in

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2003-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,14 +12,14 @@
 //*************************************************************************
 ///
 /// \file
-/// \brief Verilator: Auto version information include for all Verilated C files
+/// \brief Verilator program version information header
-///
-/// Code available from: https://verilator.org
 ///
 //*************************************************************************
 
-///**** Product and Version name
+/// Verilator product name, e.g. "Verilator"
-
 // Autoconf substitutes this with the strings from AC_INIT.
 #define VERILATOR_PRODUCT "@PACKAGE_NAME@"
+
+/// Verilator version name, e.g. "1.000 2000-01-01"
+// Autoconf substitutes this with the strings from AC_INIT.
 #define VERILATOR_VERSION "@PACKAGE_VERSION@"

include/verilated_cov.cpp

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2001-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,12 @@
 //=============================================================================
 ///
 /// \file
-/// \brief Verilator coverage analysis
+/// \brief Verilated coverage analysis implementation code
+///
+/// This file must be compiled and linked against all Verilated objects
+/// that use coverage.
+///
+/// Use "verilator --coverage" to add this to the Makefile for the linker.
 ///
 //=============================================================================
 

include/verilated_cov.h

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2001-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,13 @@
 //=============================================================================
 ///
 /// \file
-/// \brief Coverage analysis support
+/// \brief Verilated coverage analysis support header
+///
+/// This must be included in user wrapper code that wants to save coverage
+/// data.
+///
+/// It declares the VerilatedCovContext::write() which writes the collected
+/// coverage information.
 ///
 //=============================================================================
 
@@ -29,7 +35,8 @@
 class VerilatedCovImp;
 
 //=============================================================================
-/// Conditionally compile coverage code
+/// Conditionally compile statements only when doing coverage (when
+/// VM_COVERAGE is defined)
 
 // clang-format off
 #ifdef VM_COVERAGE
@@ -50,7 +57,8 @@ class VerilatedCovImp;
 /// The value may be a string, or another type which will be auto-converted to a string.
 ///
 /// Some typical keys:
-///     filename        File the recording occurs in.  Defaults to __FILE__
+///
+///     filename        File the recording occurs in.  Defaults to __FILE__.
 ///     lineno          Line number the recording occurs in.  Defaults to __LINE__
 ///     column          Column number (or occurrence# for dup file/lines).  Defaults to undef.
 ///     hier            Hierarchical name.  Defaults to name()
@@ -61,13 +69,14 @@ class VerilatedCovImp;
 ///     thresh          Threshold to consider fully covered.
 ///                     If unspecified, downstream tools will determine it.
 ///
-/// Examples:
+/// Example:
 ///
-///     vluint32_t m_cases[10];
+///     vluint32_t m_cases[10];  // Storage for coverage data
-///     constructor {
+///     constructor() {
-///         for (int i=0; i<10; ++i) { m_cases[i]=0; }
+///         // Initialize
-///     }
+///         for (int i = 0; i < 10; ++i) m_cases[i] = 0;
-///     for (int i=0; i<10; ++i) {
+///         // Insert
+///         for (int i = 0; i < 10; ++i)
 ///             VL_COVER_INSERT(&m_cases[i], "comment", "Coverage Case", "i", cvtToNumStr(i));
 ///     }
 
@@ -76,7 +85,7 @@ class VerilatedCovImp;
                 covcontextp->_insertp("hier", name(), __VA_ARGS__))
 
 //=============================================================================
-/// Convert VL_COVER_INSERT value arguments to strings
+/// Convert VL_COVER_INSERT value arguments to strings, is \internal
 
 template <class T> std::string vlCovCvtToStr(const T& t) VL_PURE {
     std::ostringstream os;
@@ -86,7 +95,7 @@ template <class T> std::string vlCovCvtToStr(const T& t) VL_PURE {
 
 //=============================================================================
 //  VerilatedCov
-///  Verilator coverage per-context structure
+/// Verilator coverage per-context structure.
 /// All public methods in this class are thread safe.
 
 class VerilatedCovContext VL_NOT_FINAL : public VerilatedVirtualBase {

include/verilated_cov_key.h

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2001-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,10 @@
 //=============================================================================
 ///
 /// \file
-/// \brief Coverage item keys
+/// \brief Verilated coverage item keys internal header
+///
+/// This file is not part of the Verilated public-facing API.
+/// It is only for internal use by the Verilated library coverage routines.
 ///
 //=============================================================================
 
@@ -57,11 +60,11 @@ VLCOVGEN_ITEM("'name':'weight',      'short':'w',  'group':0, 'default':None, 'd
 
 //=============================================================================
 // VerilatedCovKey
-/// Verilator coverage global class.
+// Namespace-style static class for \internal use.
-/// This class is thread safe.
 
 class VerilatedCovKey final {
 public:
+    // Return the short key code for a given a long coverage key
     static std::string shortKey(const std::string& key) VL_PURE {
         // VLCOVGEN_SHORT_AUTO_EDIT_BEGIN
         if (key == "column") return VL_CIK_COLUMN;

include/verilated_dpi.cpp

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2009-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,12 +12,13 @@
 //=========================================================================
 ///
 /// \file
-/// \brief Verilator: DPI implementation code
+/// \brief Verilated DPI implementation code
 ///
-///     This file must be compiled and linked against all objects
+/// This file must be compiled and linked against all Verilated objects
-///     created from Verilator or called by Verilator that use the DPI.
+/// that use the DPI.
 ///
-/// Code available from: https://verilator.org
+/// Declare any DPI routine inside Verilog to add this to the Makefile for
+/// the linker.
 ///
 //=========================================================================
 

include/verilated_dpi.h

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2003-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,18 +12,19 @@
 //*************************************************************************
 ///
 /// \file
-/// \brief Verilator: Common include for all Verilated C files that use DPI
+/// \brief Verilated DPI header
 ///
-///     This file is included automatically by Verilator at the top of
+/// This file is included automatically by Verilator at the top of all C++
-///     all C++ files it generates where DPI is used.  It contains
+/// files it generates where DPI is used.  It contains DPI interface
-///     DPI interface functions required by the Verilated code.
+/// functions required by the Verilated code.
 ///
-/// Code available from: https://verilator.org
+/// This file is not part of the Verilated public-facing API.
+/// It is only for internal use.
 ///
 //*************************************************************************
 
 #ifndef VERILATOR_VERILATED_DPI_H_
-#define VERILATOR_VERILATED_DPI_H_  ///< Header Guard
+#define VERILATOR_VERILATED_DPI_H_
 
 #include "verilatedos.h"
 #include "verilated.h"  // Also presumably included by caller

include/verilated_fst_c.cpp

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2001-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,12 @@
 //=============================================================================
 ///
 /// \file
-/// \brief C++ Tracing in FST Format
+/// \brief Verilated C++ tracing in FST format implementation code
+///
+/// This file must be compiled and linked against all Verilated objects
+/// that use --trace-fst.
+///
+/// Use "verilator --trace-fst" to add this to the Makefile for the linker.
 ///
 //=============================================================================
 

include/verilated_fst_c.h

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2001-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,9 @@
 //=============================================================================
 ///
 /// \file
-/// \brief C++ Tracing in FST Format
+/// \brief Verilated tracing in FST format header
+///
+/// User wrapper code should use this header when creating FST traces.
 ///
 //=============================================================================
 // SPDIFF_OFF

include/verilated_heavy.h

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2010-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,19 +12,17 @@
 //*************************************************************************
 ///
 /// \file
-/// \brief Verilator: String include for all Verilated C files
+/// \brief Verilated string and data-type header
 ///
-///     This file is included automatically by Verilator at the top of
+/// This file is included automatically by Verilator at the top of
-///     all C++ files it generates.  It is used when strings or other
+/// all C++ files it generates.  It is used when strings or other
-///     heavyweight types are required; these contents are not part of
+/// heavyweight types are required; these contents are not part of
-///     verilated.h to save compile time when such types aren't used.
+/// verilated.h to save compile time when such types aren't used.
-///
-/// Code available from: https://verilator.org
 ///
 //*************************************************************************
 
 #ifndef VERILATOR_VERILATED_HEAVY_H_
-#define VERILATOR_VERILATED_HEAVY_H_  ///< Header Guard
+#define VERILATOR_VERILATED_HEAVY_H_
 
 #include "verilated.h"
 

include/verilated_imp.h

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2009-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,14 +12,15 @@
 //=========================================================================
 ///
 /// \file
-/// \brief Verilator: Implementation Header, only for verilated.cpp internals.
+/// \brief Verilated implementation Header, only for verilated.cpp internals.
 ///
-/// Code available from: https://verilator.org
+/// This file is not part of the Verilated public-facing API.
+/// It is only for internal use by the Verilated libraries.
 ///
 //=========================================================================
 
 #ifndef VERILATOR_VERILATED_IMP_H_
-#define VERILATOR_VERILATED_IMP_H_  ///< Header Guard
+#define VERILATOR_VERILATED_IMP_H_
 
 // clang-format off
 #if !defined(VERILATOR_VERILATED_CPP_) && !defined(VERILATOR_VERILATED_DPI_CPP_) \

include/verilated_intrinsics.h

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2003-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,17 +12,19 @@
 //*************************************************************************
 ///
 /// \file
-/// \brief Verilator: Common include for target specific intrinsics.
+/// \brief Verilator common target specific intrinsics header
 ///
-///     Code using machine specific intrinsics for optimization should
+/// This file is not part of the Verilated public-facing API.
-///     include this header rather than directly including he target
+///
-///     specific headers. We provide macros to check for availability
+/// It is only for internal use; code using machine specific intrinsics for
-///     of instruction sets, and a common mechanism to disable them.
+/// optimization should include this header rather than directly including
+/// he target specific headers. We provide macros to check for availability
+/// of instruction sets, and a common mechanism to disable them.
 ///
 //*************************************************************************
 
 #ifndef VERILATOR_VERILATED_INTRINSICS_H_
-#define VERILATOR_VERILATED_INTRINSICS_H_  ///< Header Guard
+#define VERILATOR_VERILATED_INTRINSICS_H_
 
 // clang-format off
 

include/verilated_save.cpp

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2001-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,12 @@
 //=============================================================================
 ///
 /// \file
-/// \brief C++ Tracing in VCD Format
+/// \brief Verilated save/restore implementation code
+///
+/// This file must be compiled and linked against all Verilated objects
+/// that use --savable.
+///
+/// Use "verilator --savable" to add this to the Makefile for the linker.
 ///
 //=============================================================================
 

include/verilated_save.h

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2000-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,10 @@
 //=============================================================================
 ///
 /// \file
-/// \brief Save-restore serialization of verilated modules
+/// \brief Verilated save-restore serialization header
+///
+/// This must be included in user wrapper code that wants to use
+/// save/restore.
 ///
 //=============================================================================
 

include/verilated_sc.h

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2009-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,30 +12,31 @@
 //*************************************************************************
 ///
 /// \file
-/// \brief Verilator: Common include for all Verilated SystemC files
+/// \brief Verilated SystemC header for all Verilated SystemC files
 ///
-///     This file is included automatically by Verilator at the top of
+/// This file is included automatically by Verilator at the top of all
-///     all SystemC files it generates.
+/// SystemC files it generates.  It contains functions Verilated code uses
+/// internally to connect the Verilated model into SystemC.
 ///
-/// Code available from: https://verilator.org
+/// User wrapper code is not required to include nor use anything in this
+/// header, but may prefer to include it in place of "verilated.h" when
+/// using Verilator with SystemC.
 ///
 //*************************************************************************
 
 #ifndef VERILATOR_VERILATED_SC_H_
-#define VERILATOR_VERILATED_SC_H_  ///< Header Guard
+#define VERILATOR_VERILATED_SC_H_
 
 #include "verilatedos.h"
 
 #include "systemc.h"
 
 //=============================================================================
-// VL_SC_BV_DATAP
+// For \internal use, get a pointer to m_data in the sc_bv_base class,
-// We want to get a pointer to m_data in the sc_bv_base class,
+// getting around that it is protected.  So make an exposing class, then
-// but it is protected.  So make an exposing class, then use
+// use cast magic to get at it.  Saves patching get_datap in SystemC.
-// cast magic to get at it.  Saves patching get_datap in SystemC.
-// This class is thread safe (though most of SystemC is not).
-
 #define VL_SC_BV_DATAP(bv) (VlScBvExposer::sp_datap(bv))
+// This class is thread safe (though most of SystemC is not).
 class VlScBvExposer final : public sc_bv_base {
 public:
     static const vluint32_t* sp_datap(const sc_bv_base& base) VL_MT_SAFE {

include/verilated_sym_props.h

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2003-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,22 +12,19 @@
 //*************************************************************************
 ///
 /// \file
-/// \brief Verilator: Include to provide information about symbol inspection
+/// \brief Verilated symbol inspection header
 ///
-///     This file is for inclusion by internal files that need to inspect
+/// This file is for inclusion by internal files that need to inspect
-///     specific symbols.
+/// specific symbols.
 ///
-///     User routines wanting to inspect the symbol table should use
+/// User wrapper code wanting to inspect the symbol table should use
-///     verilated_syms.h instead.
+/// verilated_syms.h instead.
-///
-///     These classes are thread safe, and read only.
-///
-/// Code available from: https://verilator.org
 ///
 //*************************************************************************
+// These classes are thread safe, and read only.
 
 #ifndef VERILATOR_VERILATED_SYM_PROPS_H_
-#define VERILATOR_VERILATED_SYM_PROPS_H_  ///< Header Guard
+#define VERILATOR_VERILATED_SYM_PROPS_H_
 
 #include "verilatedos.h"
 

include/verilated_syms.h

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2003-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,21 +12,19 @@
 //*************************************************************************
 ///
 /// \file
-/// \brief Verilator: Include to allow symbol inspection
+/// \brief Verilated symbol inspection header
 ///
-///     This file is for inclusion by files that need to inspect the symbol
+/// This file is for inclusion by user wrapper code that needs to inspect
-///     table.  It is not included in verilated.h (instead see
+/// the symbol table.  It is not included in verilated.h (instead see
-///     verilated_sym_props.h) as it requires some heavyweight C++ classes.
+/// verilated_sym_props.h) as it requires some heavyweight C++ classes.
 ///
-///     These classes are thread safe and read only. It is constructed only
+/// These classes are thread safe and read only. It is constructed only
-///     when a model is built (from the main thread).
+/// when a model is built (from the main thread).
-///
-/// Code available from: https://verilator.org
 ///
 //*************************************************************************
 
 #ifndef VERILATOR_VERILATED_SYMS_H_
-#define VERILATOR_VERILATED_SYMS_H_  ///< Header Guard
+#define VERILATOR_VERILATED_SYMS_H_
 
 #include "verilatedos.h"
 #include "verilated_heavy.h"

include/verilated_threads.cpp

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2012-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,7 +12,12 @@
 //=============================================================================
 ///
 /// \file
-/// \brief Thread pool for verilated modules
+/// \brief Verilated thread pool implementation code
+///
+/// This file must be compiled and linked against all Verilated objects
+/// that use --threads.
+///
+/// Use "verilator --threads" to add this to the Makefile for the linker.
 ///
 //=============================================================================
 

include/verilated_threads.h

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2012-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,11 @@
 //=============================================================================
 ///
 /// \file
-/// \brief Thread pool and profiling for Verilated modules
+/// \brief Verilated thread pool and profiling header
+///
+/// This file is not part of the Verilated public-facing API.
+/// It is only for internal use by Verilated library multithreaded
+/// routines.
 ///
 //=============================================================================
 

include/verilated_trace.h

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2001-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,10 @@
 //=============================================================================
 ///
 /// \file
-/// \brief Internal tracing functionality common to all formats
+/// \brief Verilated internal common-tracing header
+///
+/// This file is not part of the Verilated public-facing API.
+/// It is only for internal use by Verilated tracing routines.
 ///
 //=============================================================================
 

include/verilated_trace_imp.cpp

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2001-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,12 @@
 //=============================================================================
 ///
 /// \file
-/// \brief Implementation of tracing functionality common to all trace formats
+/// \brief Verilated common-format tracing implementation code
+///
+/// This file must be compiled and linked against all Verilated objects
+/// that use --trace.
+///
+/// Use "verilator --trace" to add this to the Makefile for the linker.
 ///
 //=============================================================================
 

include/verilated_vcd_c.cpp

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2001-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,12 @@
 //=============================================================================
 ///
 /// \file
-/// \brief C++ Tracing in VCD Format
+/// \brief Verilated C++ tracing in VCD format implementation code
+///
+/// This file must be compiled and linked against all Verilated objects
+/// that use --trace.
+///
+/// Use "verilator --trace" to add this to the Makefile for the linker.
 ///
 //=============================================================================
 

include/verilated_vcd_c.h

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2001-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,9 @@
 //=============================================================================
 ///
 /// \file
-/// \brief C++ Tracing in VCD Format
+/// \brief Verilated tracing in VCD format header
+///
+/// User wrapper code should use this header when creating VCD traces.
 ///
 //=============================================================================
 // SPDIFF_OFF

include/verilated_vcd_sc.cpp

@@ -1,7 +1,7 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //=============================================================================
 //
-// THIS MODULE IS PUBLICLY LICENSED
+// Code available from: https://verilator.org
 //
 // Copyright 2001-2021 by Wilson Snyder. This program is free software; you
 // can redistribute it and/or modify it under the terms of either the GNU
@@ -12,7 +12,12 @@
 //=============================================================================
 ///
 /// \file
-/// \brief Verilator tracing in VCD Format
+/// \brief Verilated tracing in VCD Format implementation code
+///
+/// This file must be compiled and linked against all Verilated objects
+/// that use --trace.
+///
+/// Use "verilator --trace" to add this to the Makefile for the linker.
 ///
 //=============================================================================
 

include/verilated_vcd_sc.h

@@ -10,7 +10,10 @@
 //=============================================================================
 ///
 /// \file
-/// \brief Verilator tracing in VCD format
+/// \brief Verilated tracing in VCD format for SystemC header
+///
+/// User wrapper code should use this header when creating VCD SystemC
+/// traces.
 ///
 /// This class is not threadsafe, as the SystemC kernel is not threadsafe.
 ///

include/verilated_vpi.cpp

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2009-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,14 +12,12 @@
 //=========================================================================
 ///
 /// \file
-/// \brief Verilator: VPI implementation code
+/// \brief Verilated VPI implementation code
 ///
-///     This file must be compiled and linked against all objects
+/// This file must be compiled and linked against all Verilated objects
-///     created from Verilator or called by Verilator that use the VPI.
+/// that use the VPI.
 ///
-///     Use "verilator --vpi" to add this to the Makefile for the linker.
+/// Use "verilator --vpi" to add this to the Makefile for the linker.
-///
-/// Code available from: https://verilator.org
 ///
 //=========================================================================
 

include/verilated_vpi.h

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2009-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,17 +12,17 @@
 //=========================================================================
 ///
 /// \file
-/// \brief Verilator: VPI implementation code
+/// \brief Verilated VPI header
 ///
-///     This file must be compiled and linked against all objects
+/// This file contains routines related to using VPI with Verilated models.
-///     created from Verilator or called by Verilator that use the VPI.
 ///
-/// Code available from: https://verilator.org
+/// User wrapper code may need to include this if controlling Verilated
+/// models that use ths VPI.
 ///
 //=========================================================================
 
 #ifndef VERILATOR_VERILATED_VPI_H_
-#define VERILATOR_VERILATED_VPI_H_  ///< Header Guard
+#define VERILATOR_VERILATED_VPI_H_
 
 #include "verilatedos.h"
 #include "verilated.h"

include/verilatedos.h

@@ -1,6 +1,8 @@
 // -*- mode: C++; c-file-style: "cc-mode" -*-
 //*************************************************************************
 //
+// Code available from: https://verilator.org
+//
 // Copyright 2003-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
@@ -10,20 +12,25 @@
 //*************************************************************************
 ///
 /// \file
-/// \brief Verilator: Common include for OS portability (verilated & verilator)
+/// \brief Verilated/Verilator common header for OS portability
 ///
-///     This header is used by both the Verilator source code (run on the
+/// This header is included by user wrappers and defines the Verilated
-///     build and host system), and the Verilated output (run on the target
+/// public-facing API.
-///     system).  Code needed by only the host system goes into
-///     config_build.h.in, code needed by Verilated code only goes into
-///     verilated.h, and code needed by both goes here (verilatedos.h).
 ///
-/// Code available from: https://verilator.org
+/// User wrapper code does not generally need to include this, instead
+/// include verilated.h.
+///
+/// This header is used by both the Verilator source code (run on the build
+/// and host system), and the Verilated output (run on the target system).
+///
+/// Configuration code needed by only the host system is in
+/// config_build.h.in, code needed by Verilated code only is in
+/// verilated.h, and code needed by both is here (verilatedos.h).
 ///
 //*************************************************************************
 
 #ifndef VERILATOR_VERILATEDOS_H_
-#define VERILATOR_VERILATEDOS_H_  ///< Header Guard
+#define VERILATOR_VERILATEDOS_H_
 
 // Current clang-format versions botch #ifdef inclusion, so
 // clang-format off