Long comment at top of each CMakeLists.txt in src, libraries, modules

libraries/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+A directory containing library targets
+]]
+
 # Include the libraries that we'll build
 
 # The list of modules is ordered so that each library occurs after any others

libraries/image-compiler/CMakeLists.txt

@@ -2,7 +2,7 @@
 A small program that is run at build time of the application.  For each built-in
 theme it generates a header file from image files.  The images are part of the
 source code tree but not deployed with the program.
-]]#
+]]
 
 if( NOT IMAGE_COMPILER_EXECUTABLE )
    add_executable( image-compiler imageCompilerMain.cpp )

libraries/lib-audio-devices/CMakeLists.txt

@@ -8,7 +8,7 @@ Also abstract class Meter for communicating buffers of samples for display
 purposes.
 
 Does not contain an audio engine.
-]]#
+]]
 
 set( SOURCES
    AudioIOBase.cpp

libraries/lib-audio-unit/CMakeLists.txt

@@ -1,6 +1,6 @@
 #[[
 AudioUnit effect processing logic, minus user interface
-]]#
+]]
 
 if (USE_AUDIO_UNITS)
 

libraries/lib-basic-ui/CMakeLists.txt

@@ -11,7 +11,7 @@ There is a global pointer to an instance of Services, and the main program is
 expected, at startup, to create a static instance of a subclass of Services and
 set the pointer.  If it does not, then calls to the non-member functions in
 namespace BasicUI are no-ops.
-]]#
+]]
 
 set( SOURCES
    BasicUI.cpp

libraries/lib-breakpad-configurer/CMakeLists.txt

@@ -1,5 +1,7 @@
-# This module provides an interface to configure and start Breakpad handler 
-# in a platform independent way.
+#[[
+This library provides an interface to configure and start Breakpad handler 
+in a platform independent way.
+]]
 
 set(SOURCES 
    BreakpadConfigurer.h

libraries/lib-crashpad-configurer/CMakeLists.txt

@@ -1,5 +1,7 @@
-# This module provides an interface to configure and start Crashpad handler 
-# in a platform independent way.
+#[[
+This library provides an interface to configure and start Crashpad handler 
+in a platform independent way.
+]]
 
 set(SOURCES 
    CrashpadConfigurer.h

libraries/lib-crypto/tests/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+Unit tests for lib-crypto
+]]
+
 add_unit_test(
    NAME
       lib-crypto

libraries/lib-exceptions/CMakeLists.txt

@@ -13,7 +13,7 @@ enqueues the delayed action.
 But this library does NOT define a top-level handler for the whole application,
 to catch all otherwise uncaught exceptions. That is a responsibility of high
 level code.
-]]#
+]]
 
 set( SOURCES
    AudacityException.cpp

libraries/lib-fft/CMakeLists.txt

@@ -4,7 +4,7 @@ A library for fast fourier transforms
 
 Note -- this cannot be combined with lib-math, which depends on libsoxr, which
 includes a different version of pffft.h
-]]#
+]]
 
 set( SOURCES
    FFT.cpp

libraries/lib-files/CMakeLists.txt

@@ -6,7 +6,7 @@ Also the definition of certain significant file paths, such as the directory
 for temporary projects.
 
 Also the global logger which can save to a file.
-]]#
+]]
 
 set( SOURCES
    AudacityLogger.cpp

libraries/lib-graphics/CMakeLists.txt

@@ -1,6 +1,6 @@
 #[[
 A library responsible for custom rendering in Audacity
-]]#
+]]
 
 set( SOURCES
    FrameStatistics.cpp

libraries/lib-import-export/riff-test-util/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+A command line testing program for tempo metadata in files
+]]
+
 add_executable(riff-test-util
    RiffTestUtil.cpp
 )

libraries/lib-import-export/tests/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+Unit tests for lib-import-export
+]]
+
 add_unit_test(
    NAME
       lib-import-export

libraries/lib-math/CMakeLists.txt

@@ -1,6 +1,6 @@
 #[[
 A library of mathematical utilities and manipulation of samples
-]]#
+]]
 
 addlib( libsoxr            soxr        SOXR        YES   YES   "soxr >= 0.1.1" )
 

libraries/lib-math/tests/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+Unit tests for lib-math
+]]
+
 add_unit_test(
    NAME
       lib-math

libraries/lib-module-manager/CMakeLists.txt

@@ -5,6 +5,7 @@ effect, generator, and analyzer plug-ins.
 Maintains persistent data in the configuration file for enablement of modules
 and plug-ins, and preferred settings.
 ]]
+
 set( SOURCES
    AsyncPluginValidator.cpp
    AsyncPluginValidator.h

libraries/lib-music-information-retrieval/tests/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+Unit tests for lib-music-information-retrieval
+]]
+
 add_compile_definitions(
    CMAKE_CURRENT_SOURCE_DIR="${CMAKE_CURRENT_SOURCE_DIR}"
 )

libraries/lib-network-manager/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+Asynchronously send and receive requests and responses over internet
+]]
+
 set(TARGET lib-network-manager)
 set( TARGET_ROOT ${CMAKE_CURRENT_SOURCE_DIR} )
 

libraries/lib-numeric-formats/tests/CMakeLists.txt

@@ -1,4 +1,7 @@
 #  SPDX-License-Identifier: GPL-2.0-or-later
+#[[
+Unit tests for lib-numeric-formats
+]]
 
 add_unit_test(
    NAME

libraries/lib-preferences/CMakeLists.txt

@@ -12,7 +12,7 @@ PreferenceInitializer is a callback for the reinitialization of preferences.
 
 FileConfig decorates wxFileConfig, with a member function to
 alert the user of failure to initialize it (as when the file is read-only).
-]]#
+]]
 
 set( SOURCES
    BasicSettings.cpp

libraries/lib-preferences/tests/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+Unit tests for lib-preferences
+]]
+
 add_unit_test(
    NAME
       lib-preferences
@@ -8,4 +12,4 @@ add_unit_test(
    LIBRARIES
       lib-preferences
       lib-wx-init
-)
+)

libraries/lib-project-history/CMakeLists.txt

@@ -2,6 +2,7 @@
 Management of undo and redo history of the project, stored as states, not
 deltas.  There is not yet persistency of undo history across sessions.
 ]]
+
 set( SOURCES
    ProjectHistory.cpp
    ProjectHistory.h

libraries/lib-project/CMakeLists.txt

@@ -7,7 +7,7 @@ Also a global array of existing projects.
 
 Also ProjectStatus, an abstraction of the status bar, just holding some strings
 and formatter functions, and emitting events when changed.
-]]#
+]]
 
 set( SOURCES
    Project.cpp

libraries/lib-registries/CMakeLists.txt

@@ -25,7 +25,7 @@ Registry implements trees of objects identified by textual paths, and allows
 scattered code to insert items or subtrees at specified paths.  Registry
 computes the merging of trees, and supports visitation.  It is used notably
 by the tree of menus, allowing insertion of menu items in decoupled code.
-]]#
+]]
 
 set( SOURCES
    AttachedVirtualFunction.h

libraries/lib-screen-geometry/CMakeLists.txt

@@ -1,7 +1,7 @@
 #[[
 Classes relating to the mappings between x or y coordinates of the screen, and
 times, or frequencies, or amplitudes.
-]]#
+]]
 
 set( SOURCES
    NumberScale.h

libraries/lib-sentry-reporting/CMakeLists.txt

@@ -1,7 +1,7 @@
 #[[
 A library, that allows sending error reports to a Sentry server
 using Exception and Message interfaces.
-]]#
+]]
 
 set( TARGET lib-sentry-reporting )
 set( TARGET_ROOT ${CMAKE_CURRENT_SOURCE_DIR} )

libraries/lib-snapping/CMakeLists.txt

@@ -8,6 +8,7 @@ This library:
 3. Provides a project extension that is responsible for snapping
 
 ]]
+
 set(TARGET lib-snapping)
 set(TARGET_ROOT ${CMAKE_CURRENT_SOURCE_DIR} )
 

libraries/lib-snapping/tests/CMakeLists.txt

@@ -1,4 +1,7 @@
 #  SPDX-License-Identifier: GPL-2.0-or-later
+#[[
+Unit tests for lib-snapping
+]]
 
 add_unit_test(
    NAME

libraries/lib-sqlite-helpers/tests/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+Unit tests for lib-sqlite
+]]
+
 add_unit_test(
    NAME
       lib-sqlite-helpers

libraries/lib-stretching-sequence/CMakeLists.txt

@@ -1,8 +1,11 @@
 #[[
-A library providing a time-stretching-capable implementation of `PlayableSequence`.
+A library providing a time-stretching-capable implementation of
+`PlayableSequence`.
 
-Please refer to this directory's readme for a presentation of the constraints inherent to such an implementation.
+Please refer to this directory's readme for a presentation of the constraints
+inherent to such an implementation.
 ]]
+
 set( SOURCES
    AudioSegment.cpp
    AudioSegment.h

libraries/lib-stretching-sequence/tests/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+Unit tests for lib-stretching-sequence
+]]
+
 add_compile_definitions(CMAKE_SOURCE_DIR="${CMAKE_SOURCE_DIR}")
 
 add_unit_test(

libraries/lib-string-utils/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+String encoding and formatting utilities
+]]
+
 set(TARGET lib-string-utils)
 set(TARGET_ROOT ${CMAKE_CURRENT_SOURCE_DIR} )
 

libraries/lib-string-utils/tests/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+Unit tests for lib-string-utils
+]]
+
 add_unit_test(
    NAME
       lib-string-utils

libraries/lib-strings/CMakeLists.txt

@@ -11,7 +11,7 @@ even if the global choice of locale changes during its lifetime.  It does not
 implicitly interconvert with wxString.
 
 This library depends only on the wxBase subset of wxWidgets.
-]]#
+]]
 
 set( SOURCES
    Base64.h

libraries/lib-theme/CMakeLists.txt

@@ -1,7 +1,7 @@
 #[[
 A library to hold a registry of image and color identifiers, and multiple themes
 associating data with those identifiers.
-]]#
+]]
 
 set( SOURCES
    AColor.cpp

libraries/lib-time-and-pitch/tests/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+Unit tests for lib-time-and-pitch
+]]
+
 add_compile_definitions(CMAKE_SOURCE_DIR="${CMAKE_SOURCE_DIR}")
 
 add_unit_test(

libraries/lib-url-schemes/CMakeLists.txt

@@ -2,6 +2,7 @@
 #[[
 Library, responsible for handling custom URL scemas.
 ]]
+
 set( SOURCES
    URLSchemesRegistry.cpp
    URLSchemesRegistry.h

libraries/lib-utility/CMakeLists.txt

@@ -12,8 +12,7 @@ did not yet provide std::make_unique.  That explains the name.
 Audacity now uses C++17, and yet, need arose for other anticipations of future
 standards.  It also provides other pervasively used utilities that don't
 correspond to things in the standard.
-
-]]#
+]]
 
 set( SOURCES
    AppEvents.cpp

libraries/lib-utility/tests/CMakeLists.txt

@@ -1,4 +1,7 @@
 #  SPDX-License-Identifier: GPL-2.0-or-later
+#[[
+Unit tests for lib-utility
+]]
 
 add_unit_test(
    NAME

libraries/lib-uuid/CMakeLists.txt

@@ -1,3 +1,7 @@
+#[[
+Generation of UUIDs
+]]
+
 set( TARGET lib-uuid )
 set( TARGET_ROOT ${CMAKE_CURRENT_SOURCE_DIR} )
 

libraries/lib-viewport/CMakeLists.txt

@@ -2,6 +2,7 @@
 Viewport defines a callback facade for horizontal and vertical scrollbars, and
 provides methods to scroll and zoom the view of tracks.
 ]]
+
 set( SOURCES
    Viewport.cpp
    Viewport.h

libraries/lib-vst/CMakeLists.txt

@@ -1,6 +1,6 @@
 #[[
 VST 2 effect plugin discovery and processing logic, without user interface
-]]#
+]]
 
 set( SOURCES
    VSTEffectBase.cpp

libraries/lib-wx-init/CMakeLists.txt

@@ -1,7 +1,7 @@
 #[[
 Startup time injections of wxWidgets based implementations of services behind
 toolkit-neutral facades
-]]#
+]]
 
 set( SOURCES
    AccessibleLinksFormatter.cpp

libraries/lib-xml/CMakeLists.txt

@@ -3,7 +3,7 @@ Utilities to serialize and deserialize trees of objects in XML form, and a
 class template XMLMethodRegistry to generate registries for serializable
 objects attached to a host object.  The template is parametrized by the host
 type.
-]]#
+]]
 
 set( SOURCES
    XMLAttributeValueView.cpp