Update descriptions

Author: urbytes21

src/dp/creational/AbstractFactory.cpp

@@ -1,7 +1,13 @@
 // cppcheck-suppress-file [functionStatic]
 
-// Abstract Factory is a creational design pattern that lets you produce
-// families of related objects without specifying their concrete classes.
+// Abstract Factory — create families of related products without concrete types.
+//
+// Flow in this file:
+//   1. Define product interfaces             -> IGdbProduct, ICMakeProduct
+//   2. Implement concrete products per OS    -> Linux / Windows / MacOs variants
+//   3. Define an abstract factory            -> IProductAbstractFactory
+//   4. Implement concrete factories          -> one factory = one matching family
+//   5. Client uses one factory for all products -> products stay consistent (same OS)
 
 #include <memory>
 #include <string>

src/dp/creational/Builder.cpp

@@ -1,5 +1,12 @@
 // cppcheck-suppress-file [functionStatic]
 
+// Flow in this file:
+//   1. Define the product being built        -> Product (parts list)
+//   2. Define a builder interface            -> IBuilder (produce_part_N / build)
+//   3. Share common builder state            -> AbstractBuilder (reset / product_)
+//   4. Implement concrete builders           -> SimpleBuilder / ComplexBuilder
+//   5. Client chains steps, then build()     -> same steps, different representations
+
 #include <memory>
 #include <ostream>
 #include <sstream>

src/dp/creational/FactoryMethod.cpp

@@ -1,5 +1,12 @@
 // cppcheck-suppress-file [functionStatic]
 
+// Flow in this file:
+//   1. Define a product interface            -> IGdbProduct
+//   2. Implement concrete products           -> Linux / Windows / MacOs Gdb
+//   3. Define a creator interface            -> IGdbFactory (+ AbstractGdbFactory)
+//   4. Implement concrete creators           -> Linux / Windows / MacOs factories
+//   5. Client picks a factory, then uses it  -> never constructs products directly
+
 #include <memory>
 #include <string>
 #include "ExampleRegistry.h"

src/dp/creational/Prototype.cpp

@@ -1,135 +1,131 @@
 // cppcheck-suppress-file [functionStatic]
 
-// Prototype is a creational design pattern that lets you "copy existing objects" without making your code "dependent on their classes".
-// Appicability:
-// (*)  when your code shouldn’t depend on the concrete classes of objects that you need to copy.
-// (**) when you want to reduce the number of subclasses that only differ in the way they initialize their respective objects.
-
-// UML: docs/uml/patterns_behavioral_prototype.drawio.svg
-
+// Prototype = create new objects by cloning existing ones.
+//
+// Flow in this file:
+//   1. Define a cloneable interface          -> IExtensionPrototype
+//   2. Implement concrete prototypes         -> Logger / Analytics
+//   3. (Optional) Store named presets        -> ExtensionPrototypeRegistry
+//   4. Client asks registry to clone by id   -> never mentions concrete types
+
+#include <memory>
+#include <string>
+#include <string_view>
 #include <unordered_map>
 #include <utility>
+
+#include "ExampleRegistry.h"
 #include "Logger.h"
+
 namespace {
 namespace prototy {
 
-constexpr std::string_view kLoggerEtxId = "logger";
+constexpr std::string_view kLoggerExtId = "logger";
 constexpr std::string_view kAnalyzeId = "analyze";
 
-/*
- * Prototype interface declares the cloning methods.
- * In most cases, it’s a single `clone` method.
- */
+/// @class Prototype interface: "I know how to copy myself."
+/// @brief client code only depends on this class
 class IExtensionPrototype {
  public:
   virtual ~IExtensionPrototype() = default;
-  virtual IExtensionPrototype* clone() = 0;
+
+  /// return a new object
+  virtual std::unique_ptr<IExtensionPrototype> clone() const = 0;
+
   virtual void execute() const = 0;
 };
 
-/*
- * Concrete Prototype implement an operation for cloning itself
- * In addition to copying the original object’s data to the clone,
- * this method may also handle some edge cases of the cloning process related to cloning linked objects,
- * untangling recursive dependencies, etc.
- */
+/// @class Concrete Prototype
+/// @brief each class copies itself
 class LoggerExtension : public IExtensionPrototype {
- private:
-  std::string log_level_;
-
  public:
   explicit LoggerExtension(std::string level = "DEBUG")
       : log_level_{std::move(level)} {}
 
-  IExtensionPrototype* clone() override { return new LoggerExtension(*this); }
+  std::unique_ptr<IExtensionPrototype> clone() const override {
+    return std::make_unique<LoggerExtension>(*this);
+  }
 
   void execute() const override { LOG("log level: " + log_level_); }
-};
 
-class AnalyticsExtension : public IExtensionPrototype {
  private:
-  int sRate_;
+  std::string log_level_;
+};
 
+class AnalyticsExtension : public IExtensionPrototype {
  public:
-  explicit AnalyticsExtension(int level = 1) : sRate_{level} {}
+  explicit AnalyticsExtension(int sampling_rate = 1)
+      : sampling_rate_{sampling_rate} {}
 
-  IExtensionPrototype* clone() override {
-    return new AnalyticsExtension(*this);
+  std::unique_ptr<IExtensionPrototype> clone() const override {
+    return std::make_unique<AnalyticsExtension>(*this);
   }
 
-  void execute() const override { LOG_S("sampling rate: " << sRate_); }
-};
+  void execute() const override { LOG_S("sampling rate: " << sampling_rate_); }
 
-/**
- * Prototype Registry provides an easy way to access frequently-used prototypes.
- * It stores a set of pre-built objects that are ready to be copied.
- * The simplest prototype registry is a name ^ prototype hash map.
- * However, if you need better search criteria than a simple name, you can build a much more robust version of the registry.
- */
-class ExtensionPrototypeRegistry {
  private:
-  std::unordered_map<std::string, IExtensionPrototype*> prototypes_;
+  int sampling_rate_;
+};
 
+/// @class Prototype Registry
+/// @brief a map of named presets ready to be cloned.
+class ExtensionPrototypeRegistry {
  public:
-  ~ExtensionPrototypeRegistry() {
-    for (auto it = prototypes_.begin(); it != prototypes_.end();) {
-      delete it->second;           // free the pointer
-      it = prototypes_.erase(it);  // erase and move to next
-    }
-  }
-  void register_extension(const std::string_view& id,
-                          IExtensionPrototype* proto) {
+  void register_extension(std::string_view id,
+                          std::unique_ptr<IExtensionPrototype> proto) {
     LOG(id);
-    prototypes_[std::string(id)] = proto;
+    prototypes_[std::string(id)] = std::move(proto);
   }
 
-  IExtensionPrototype* create(const std::string_view& id) const {
+  /// clone the preset for `id`. Returns nullptr if the id is unknown.
+  std::unique_ptr<IExtensionPrototype> create(std::string_view id) const {
     auto it = prototypes_.find(std::string(id));
-    if (it != prototypes_.end()) {
-      return it->second->clone();
+    if (it == prototypes_.end()) {
+      return nullptr;
     }
-    return nullptr;
+    return it->second->clone();  // copy the template, leave the original intact
   }
+
+ private:
+  std::unordered_map<std::string, std::unique_ptr<IExtensionPrototype>>
+      prototypes_;
 };
 
 void run() {
-  // Client creates a new object by asking a prototype to clone itself
-  auto client_code = [](const ExtensionPrototypeRegistry* const registry) {
-    IExtensionPrototype* logger_etx = registry->create(prototy::kLoggerEtxId);
-    logger_etx->execute();
-    IExtensionPrototype* analyx_etx = registry->create(prototy::kAnalyzeId);
-    analyx_etx->execute();
-
-    delete logger_etx;
-    delete analyx_etx;
+  // build presets once, register by name
+  ExtensionPrototypeRegistry registry;
+  registry.register_extension(kLoggerExtId,
+                              std::make_unique<LoggerExtension>("DEBUG"));
+  registry.register_extension(kAnalyzeId,
+                              std::make_unique<AnalyticsExtension>(1200));
+
+  // create-by-clone
+  auto client_code = [](const ExtensionPrototypeRegistry& reg) {
+    auto logger_ext = reg.create(kLoggerExtId);
+    auto analytics_ext = reg.create(kAnalyzeId);
+
+    if (logger_ext) {
+      logger_ext->execute();
+    }
+    if (analytics_ext) {
+      analytics_ext->execute();
+    }
   };
 
-  // Create a registry
-  auto* registry = new ExtensionPrototypeRegistry();
-
-  // Register extensions
-  registry->register_extension(prototy::kLoggerEtxId,
-                               new LoggerExtension("DEBUG"));
-  registry->register_extension(prototy::kAnalyzeId,
-                               new AnalyticsExtension(1200));
-
   client_code(registry);
-
-  delete registry;
 }
+
 }  // namespace prototy
 }  // namespace
 
-#include "ExampleRegistry.h"
-
 class PrototypeExample : public IExample {
  public:
   std::string group() const override { return "dp/creational"; }
   std::string name() const override { return "Prototype"; }
   std::string description() const override {
-    return "Prototype Pattern Example";
+    return "Clone configured objects via a prototype interface + registry";
   }
   void execute() override { prototy::run(); }
 };
 
-REGISTER_EXAMPLE(PrototypeExample);
+REGISTER_EXAMPLE(PrototypeExample);

src/dp/creational/Singleton.cpp

@@ -1,5 +1,13 @@
 // cppcheck-suppress-file [functionStatic]
 
+// Singleton — ensure a class has only one instance, accessed globally.
+//
+// Flow in this file:
+//   1. Hide the constructor                  -> private SingletonConfig()
+//   2. Ban copy / assign                     -> deleted special members
+//   3. Expose a single access point          -> get_instance() (Meyers' singleton)
+//   4. Client always uses get_instance()     -> same object everywhere
+
 #include <string>
 #include "ExampleRegistry.h"
 #include "Logger.h"