📝 remove duplicate constructor docs

2026-08-02 16:34:34 +00:00 · 2026-06-13 23:31:41 +08:00
parent bb39091830
commit d47109aa54
5 changed files with 0 additions and 372 deletions
@@ -87,7 +87,6 @@ BitLogger API navigation.
 - [format-text.md](./format-text.md)
 - [format-json.md](./format-json.md)
 - [text-formatter-config.md](./text-formatter-config.md)
 - [text-formatter-config-new.md](./text-formatter-config-new.md)
 - [default-text-formatter-config.md](./default-text-formatter-config.md)
 - [text-formatter-config-to-formatter.md](./text-formatter-config-to-formatter.md)
 - [text-formatter-config-to-json.md](./text-formatter-config-to-json.md)
@@ -222,15 +221,12 @@ BitLogger API navigation.
 - [file-rotation-config-to-json.md](./file-rotation-config-to-json.md)
 - [queue-config-type.md](./queue-config-type.md)
 - [queue-config.md](./queue-config.md)
 - [queue-config-new.md](./queue-config-new.md)
 - [queue-config-to-json.md](./queue-config-to-json.md)
 - [stringify-queue-config.md](./stringify-queue-config.md)
 - [sink-config-type.md](./sink-config-type.md)
 - [default-sink-config.md](./default-sink-config.md)
 - [sink-config-new.md](./sink-config-new.md)
 - [logger-config.md](./logger-config.md)
 - [logger-config-type.md](./logger-config-type.md)
 - [logger-config-new.md](./logger-config-new.md)
 - [default-logger-config.md](./default-logger-config.md)
 - [logger-config-to-json.md](./logger-config-to-json.md)
 - [stringify-logger-config.md](./stringify-logger-config.md)
@@ -1,90 +0,0 @@
 ---
 name: logger-config-new
 group: api
 category: config
 update-time: 20260613
 description: Construct the main LoggerConfig value for config-driven runtime logger assembly.
 key-word:
    - logger
    - config
    - constructor
    - public
 ---
 ## Logger-config-new
 Construct a `LoggerConfig` value for config-driven runtime logger assembly. This constructor stores level, target, timestamp behavior, sink shape, and optional queue wrapping as one typed config object.
 ### Interface
 ```moonbit
 pub fn LoggerConfig::new(
  min_level~ : Level = Level::Info,
  target~ : String = "",
  timestamp~ : Bool = false,
  sink~ : SinkConfig = default_sink_config(),
  queue~ : QueueConfig? = None,
 ) -> LoggerConfig {
 ```
 #### input
 - `min_level : Level` - Global level gate.
 - `target : String` - Default target namespace.
 - `timestamp : Bool` - Whether the built logger should emit timestamps.
 - `sink : SinkConfig` - Configured sink shape.
 - `queue : QueueConfig?` - Optional synchronous queue wrapper.
 #### output
 - `LoggerConfig` - Main logger configuration object.
 ### Explanation
 Detailed rules explaining key parameters and behaviors
 - The constructor stores the supplied logging policy and sink config directly.
 - `min_level` defaults to `Level::Info`, `target` defaults to `""`, and `timestamp` defaults to `false`.
 - `sink` defaults to `default_sink_config()`.
 - `queue=None` means no configured synchronous queue layer.
 ### How to Use
 Here are some specific examples provided.
 #### When Build Config In Code Instead Of JSON
 When application bootstrapping prefers typed config values:
 ```moonbit
 let config = LoggerConfig::new(
  min_level=Level::Warn,
  target="svc",
  timestamp=true,
  sink=SinkConfig::new(kind=SinkKind::TextConsole),
 )
 ```
 In this example, the logger configuration is explicit and strongly typed.
 #### When Prepare Config For A Later Builder
 When config is assembled in one place and built later:
 ```moonbit
 let config = LoggerConfig::new(queue=Some(QueueConfig::new(16)))
 let logger = build_logger(config)
 ```
 In this example, the config object becomes the handoff boundary between assembly and runtime construction.
 ### Error Case
 e.g.:
 - If `sink` describes a capability-limited backend shape such as native file output on a non-native target, later runtime behavior still follows backend support rules.
 - If `target` is empty, the configuration is still valid.
 ### Notes
 1. This is the core typed constructor for sync logger assembly.
 2. Prefer this API when config is generated in code rather than parsed from text.
@@ -1,78 +0,0 @@
 ---
 name: queue-config-new
 group: api
 category: config
 update-time: 20260613
 description: Construct a QueueConfig value for config-driven synchronous queue wrapping.
 key-word:
    - queue
    - config
    - constructor
    - public
 ---
 ## Queue-config-new
 Construct a `QueueConfig` value for config-driven synchronous queue wrapping. This constructor stores queue capacity and overflow behavior as data for later logger assembly.
 ### Interface
 ```moonbit
 pub fn QueueConfig::new(
  max_pending : Int,
  overflow~ : QueueOverflowPolicy = QueueOverflowPolicy::DropNewest,
 ) -> QueueConfig {
 ```
 #### input
 - `max_pending : Int` - Queue capacity used by the configured queue wrapper.
 - `overflow : QueueOverflowPolicy` - Overflow strategy used when the queue is full.
 #### output
 - `QueueConfig` - Queue configuration value suitable for `LoggerConfig` or JSON serialization helpers.
 ### Explanation
 Detailed rules explaining key parameters and behaviors
 - The constructor stores `max_pending` and `overflow` directly without additional normalization.
 - This config is used by `build_logger(...)` and `parse_and_build_logger(...)` when `queue` is present in `LoggerConfig`.
 - It configures the synchronous `QueuedSink`, not the async adapter package.
 - `overflow` defaults to `QueueOverflowPolicy::DropNewest`.
 ### How to Use
 Here are some specific examples provided.
 #### When Need Config-driven Bounded Queueing
 When runtime queue wrapping should be described as config data:
 ```moonbit
 let queue = QueueConfig::new(32, overflow=QueueOverflowPolicy::DropOldest)
 ```
 In this example, queue capacity and overflow behavior are captured for later runtime assembly.
 #### When Embed Queue Config In Logger Config
 When queueing should be part of a larger logger configuration object:
 ```moonbit
 let config = LoggerConfig::new(queue=Some(QueueConfig::new(16)))
 ```
 In this example, queue config becomes one component of the top-level logger config.
 ### Error Case
 e.g.:
 - If `max_pending` is too small, configured runtime drops may happen frequently under bursty load.
 - If queue config is omitted from `LoggerConfig`, no synchronous queue wrapper is added.
 ### Notes
 1. This constructor is for config-driven queue wrapping, not `bitlogger_async`.
 2. Use `Logger::with_queue(...)` when queue composition should be done directly in code.
@@ -1,93 +0,0 @@
 ---
 name: sink-config-new
 group: api
 category: config
 update-time: 20260613
 description: Construct a SinkConfig value for config-driven logger sink selection.
 key-word:
    - sink
    - config
    - constructor
    - public
 ---
 ## Sink-config-new
 Construct a `SinkConfig` value for config-driven logger assembly. This constructor stores sink shape and sink-specific settings as typed data for later runtime building.
 ### Interface
 ```moonbit
 pub fn SinkConfig::new(
  kind~ : SinkKind = SinkKind::Console,
  path~ : String = "",
  append~ : Bool = true,
  auto_flush~ : Bool = true,
  rotation~ : FileRotation? = None,
  text_formatter~ : TextFormatterConfig = default_text_formatter_config(),
 ) -> SinkConfig {
 ```
 #### input
 - `kind : SinkKind` - Sink variant such as `Console`, `JsonConsole`, `TextConsole`, or `File`.
 - `path : String` - File path used when `kind=File`.
 - `append : Bool` - File append policy.
 - `auto_flush : Bool` - File auto-flush policy.
 - `rotation : FileRotation?` - Optional file rotation policy.
 - `text_formatter : TextFormatterConfig` - Formatter config used by text console or file text rendering.
 #### output
 - `SinkConfig` - Typed sink configuration used by `LoggerConfig`.
 ### Explanation
 Detailed rules explaining key parameters and behaviors
 - The constructor stores the supplied sink-shape and file-specific fields directly.
 - `kind` defaults to `SinkKind::Console`.
 - `text_formatter` defaults to `default_text_formatter_config()` so text-oriented sink config always has a formatter config available.
 - File-only options are stored even though only `kind=File` actually consumes them at runtime.
 ### How to Use
 Here are some specific examples provided.
 #### When Build A Text Console Config
 When runtime output should be text-formatted through config data:
 ```moonbit
 let sink = SinkConfig::new(
  kind=SinkKind::TextConsole,
  text_formatter=TextFormatterConfig::new(show_timestamp=false),
 )
 ```
 In this example, the formatter choice is embedded directly into sink config.
 #### When Build A File Sink Config
 When file behavior should be data-driven:
 ```moonbit
 let sink = SinkConfig::new(
  kind=SinkKind::File,
  path="app.log",
  rotation=Some(file_rotation(1024, max_backups=2)),
 )
 ```
 In this example, file location and retention policy are part of the same sink definition.
 ### Error Case
 e.g.:
 - If `kind=File` but `path` is empty, the config object is still constructible, but runtime usage should be evaluated carefully.
 - If `kind` is non-file, file-specific options may simply be unused by the runtime builder.
 ### Notes
 1. This constructor builds sink-shape configuration, not the runtime sink itself.
 2. Use `sink_config_to_json(...)` and `stringify_sink_config(...)` for export.
@@ -1,107 +0,0 @@
 ---
 name: text-formatter-config-new
 group: api
 category: config
 update-time: 20260613
 description: Construct a TextFormatterConfig value for config-driven text formatting.
 key-word:
    - formatter
    - config
    - constructor
    - public
 ---
 ## Text-formatter-config-new
 Construct a `TextFormatterConfig` value for config-driven text formatting. This constructor stores text formatting options as serializable data that can later be converted into a runtime `TextFormatter`.
 ### Interface
 ```moonbit
 pub fn TextFormatterConfig::new(
  show_timestamp~ : Bool = true,
  show_level~ : Bool = true,
  show_target~ : Bool = true,
  show_fields~ : Bool = true,
  separator~ : String = " ",
  field_separator~ : String = " ",
  template~ : String = "",
  color_mode~ : ColorMode = ColorMode::Never,
  color_support~ : ColorSupport = ColorSupport::TrueColor,
  style_markup~ : StyleMarkupMode = StyleMarkupMode::Full,
  target_style_markup~ : StyleMarkupMode = StyleMarkupMode::Disabled,
  fields_style_markup~ : StyleMarkupMode = StyleMarkupMode::Disabled,
  style_tags~ : Map[String, TextStyle] = {},
 ) -> TextFormatterConfig {
 ```
 #### input
 - `show_timestamp : Bool` - Whether formatted text should include timestamps.
 - `show_level : Bool` - Whether formatted text should include the record level.
 - `show_target : Bool` - Whether formatted text should include the record target.
 - `show_fields : Bool` - Whether formatted text should include structured fields.
 - `separator : String` - Separator used between the main rendered parts.
 - `field_separator : String` - Separator used between rendered fields.
 - `template : String` - Optional text template used by the runtime formatter.
 - `color_mode : ColorMode` - Color-emission policy for the runtime formatter.
 - `color_support : ColorSupport` - Color capability level used when color is enabled.
 - `style_markup : StyleMarkupMode` - Markup handling for the main formatted output.
 - `target_style_markup : StyleMarkupMode` - Markup handling for the rendered target field.
 - `fields_style_markup : StyleMarkupMode` - Markup handling for rendered field values.
 - `style_tags : Map[String, TextStyle]` - Local tag definitions stored as plain config data.
 #### output
 - `TextFormatterConfig` - Config object that can later be serialized or converted to a runtime formatter.
 ### Explanation
 Detailed rules explaining key parameters and behaviors
 - The constructor stores the supplied formatting options directly as config data.
 - Default values match the normal config-oriented text formatting defaults, including `color_mode=ColorMode::Never` and markup settings for full main-output markup with disabled target and field markup.
 - `style_tags` are stored as concrete `TextStyle` values instead of a runtime registry.
 - This constructor is the main typed entry point for formatter config used by `SinkConfig`, `LoggerConfig`, and JSON parse/stringify workflows.
 ### How to Use
 Here are some specific examples provided.
 #### When Need Config-built Text Output
 When text formatting should be configured rather than hard-coded:
 ```moonbit
 let formatter = TextFormatterConfig::new(
  show_timestamp=false,
  template="[{level}] {message}",
  color_mode=ColorMode::Always,
 )
 ```
 In this example, formatter settings are stored as config rather than a runtime-only formatter.
 #### When Embed Formatter Config In Sink Config
 When a text-rendering policy should be part of a larger sink definition:
 ```moonbit
 let sink = SinkConfig::new(
  kind=SinkKind::TextConsole,
  text_formatter=TextFormatterConfig::new(show_target=false),
 )
 ```
 In this example, formatter config becomes one field in a broader sink configuration object.
 ### Error Case
 e.g.:
 - If `template` is empty, later runtime formatting falls back to the normal part-assembly path.
 - If `style_tags` is empty, no local formatter tag registry is created when converting to a runtime formatter.
 ### Notes
 1. Prefer this constructor when formatter behavior must be stored, parsed, or serialized.
 2. Prefer `text_formatter(...)` when writing direct runtime code without config objects.