fix the event code; update docs

dbt_common/behavior_flags.py

@@ -15,11 +15,11 @@
 
 class BehaviorFlag(TypedDict):
     """
-    A set of config used to create a BehaviorFlag
+    Configuration used to create a BehaviorFlagRendered instance
 
     Args:
         name: the name of the behavior flag
-        default:  default setting, starts as False, becomes True in the next minor release
+        default: default setting, starts as False, becomes True after a bake-in period
         deprecation_version: the version when the default will change to True
         deprecation_message: an additional message to send when the flag evaluates to False
         docs_url: the url to the relevant docs on docs.getdbt.com
@@ -35,7 +35,7 @@ class BehaviorFlag(TypedDict):
 
 class BehaviorFlagRendered:
     """
-    The canonical behavior flag that gets used through dbt packages
+    A rendered behavior flag that gets used throughout dbt packages
 
     Args:
         flag: the configuration for the behavior flag
@@ -73,7 +73,7 @@ def _deprecation_event(self, flag: BehaviorFlag) -> BehaviorDeprecationEvent:
     @staticmethod
     def _default_source() -> str:
         """
-        If the maintainer did not provide a source, default to the module that called `register`.
+        If the maintainer did not provide a source, default to the module that called this class.
         For adapters, this will likely be `dbt.adapters.<foo>.impl` for `dbt-foo`.
         """
         for frame in inspect.stack():
@@ -86,9 +86,22 @@ def __bool__(self) -> bool:
         return self.setting
 
 
-# this is effectively a dictionary that supports dot notation
-# it makes usage easy, e.g. adapter.behavior.my_flag
 class Behavior:
+    """
+    A collection of behavior flags
+
+    This is effectively a dictionary that supports dot notation for easy reference, e.g.:
+        ```python
+        if adapter.behavior.my_flag:
+            ...
+        ```
+        ```jinja
+        {% if adapter.behavior.my_flag %}
+            ...
+        {% endif %}
+        ```
+    """
+
     _flags: List[BehaviorFlagRendered]
 
     def __init__(self, flags: List[BehaviorFlag], user_overrides: Dict[str, Any]) -> None:

dbt_common/events/types.proto

@@ -25,7 +25,7 @@ message GenericMessage {
 
 // D - Deprecations
 
-// D042
+// D018
 message BehaviorDeprecationEvent {
     string flag_name = 1;
     string flag_source = 2;

dbt_common/events/types.py

@@ -46,7 +46,7 @@ class BehaviorDeprecationEvent(WarnLevel):
     docs_url: Optional[str]
 
     def code(self) -> str:
-        return "D042"  # TODO: update this to the next unused code
+        return "D018"
 
     def message(self) -> str:
         msg = f"The legacy behavior controlled by `{self.flag_name}` is deprecated.\n"