Source Format Enforcement (#1234)

[thirdparty/squid.git] / src / base / Packable.h

diff --git a/src/base/Packable.h b/src/base/Packable.h
index 1df486abc853d89ce1d245345e52d421b91810b1..046c118558e93ec2f89a0cbf1e80ff2682df73a6 100644 (file)
--- a/src/base/Packable.h
+++ b/src/base/Packable.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
+ * Copyright (C) 1996-2023 The Squid Software Foundation and contributors
  *
  * Squid software is distributed under GPLv2+ license and includes
  * contributions from numerous individuals and organizations.
@@ -45,6 +45,9 @@
  * Thus, one can write just one function that will take a Packable object
  * and either "pack" things for Comm::Write or "append" things to Store,
  * depending on actual Packable object supplied.
+ *
+ * XXX: Misnamed. This is a Packer or Packager API (i.e., "something that packs
+ * or packages others"); this is not a "something that can be packed" API.
  */
 class Packable
 {
@@ -67,6 +70,12 @@ public:
      *
      * \note arguments may be evaluated more than once, be careful
      *       of side-effects
+     *
+     * XXX: This method either should not exist or should not be virtual.
+     * Kids should not be forced to re-implement vappendf() logic.
+     * That logic should be implemented once, using other [Packable] APIs.
+     * Packable is not about providing a printf(3) service. Packable
+     * is about writing opaque data to various custom destinations.
      */
     virtual void vappendf(const char *fmt, va_list ap) = 0;