feat: Implement systematic format logic documentation injection

ddoc/source/preprocessor.d

@@ -63,6 +63,7 @@ All unknown options are passed to the compiler.
     text = genChangelogVersion(inputFile, text);
     text = genSwitches(text);
     text = fixDdocBugs(inputFile, text);
+    text = injectFmtLogic(inputFile, text);
 
     // Phobos index.d should have been named index.dd
     if (inputFile.endsWith(".d") && !inputFile.endsWith("index.d"))
@@ -503,3 +504,18 @@ string fixDdocBugs(string inputFile, string text)
     }
     return text;
 }
+
+// injects format logic documentation to relevant functions
+string injectFmtLogic(string fileName, string text)
+{
+    if (fileName.canFind("std/stdio.d") || fileName.canFind("std/format.d") || fileName.canFind("std/format/package.d"))
+    {
+        import std.regex : regex, replaceAll;
+        // Add a notice about format logic syntax to common functions in these modules.
+        // It's added as an additional ddoc line just before the function/declaration.
+        // DMD will merge these sequential ddoc comments.
+        static auto re = regex(`((\s*)(?:///.*|/\*\*[\s\S]*?\*/))\n(\s*)(?=.*(writefl?n|readfl?n|format|formattedRead|formattedWrite)\s*\()`, "gm");
+        return text.replaceAll(re, "$1\n$3/// $(FMT_LOGIC)\n$3");
+    }
+    return text;
+}

dlang.org.ddoc

@@ -146,6 +146,21 @@ DDOCKEYVAL2=$(DIVC keyval $1, $(SPANC key key$1, $2:) $(DIVC val val$1, $(TAIL $
 DDSUBLINK=$(LINK2 $(ROOT_DIR)$1.html#$2, $3)
 _=
 
+FMT_LOGIC = $(DIVC message-box message-box-gray, $(B Format Logic) — For detailed information on the formatting syntax, see the $(LINK2 $(ROOT_DIR)format.html, Format Logic) page. $(LF) $(LF) $(FMT_LOGIC_TABLE) )
+
+FMT_LOGIC_TABLE = $(BOOKTABLE Format specifiers,
+    $(TR $(TH Specifier) $(TH Description))
+    $(TR $(TD $(D %s)) $(TD Default "string" representation))
+    $(TR $(TD $(D %d)) $(TD Signed integer (decimal)))
+    $(TR $(TD $(D %f)) $(TD Floating point))
+    $(TR $(TD $(D %x) / $(D %X)) $(TD Hexadecimal (lowercase / uppercase)))
+    $(TR $(TD $(D %b)) $(TD Binary))
+    $(TR $(TD $(D %(...%))) $(TD Array/Range formatting))
+    $(TR $(TD $(D %?)) $(TD Boolean))
+)
+
+_=
+
 
 DMDSRC=$(HTTPS github.com/dlang/dmd/blob/master/src/dmd/$0, $0)
 DOT_PREFIXED=.$1$(DOT_PREFIXED $+)
@@ -288,6 +303,7 @@ NAVIGATION_DOCUMENTATION=
 $(SUBMENU_MANUAL
     $(SUBMENU_LINK $(ROOT_DIR)spec/spec.html, Language Reference)
     $(SUBMENU_LINK $(ROOT_DIR)phobos/index.html, Library Reference)
+    $(SUBMENU_LINK $(ROOT_DIR)format.html, Format Logic)
     $(SUBMENU_LINK $(ROOT_DIR)dmd.html, Command-line Reference)
     $(SUBMENU_LINK_DIVIDER $(ROOT_DIR)comparison.html, Feature Overview)
     $(SUBMENU_LINK $(ROOT_DIR)articles.html, Articles)

format.dd

@@ -0,0 +1,54 @@
+Ddoc
+
+$(D_S Format Logic,
+
+$(SECTION1 Formatting Options,
+    $(P Many functions in D, such as $(REF writefln, std,stdio) and $(REF format, std,format), use format strings to control how data is presented.)
+
+    $(H2 Basic Syntax)
+    $(D_CODE writefln("format string", arguments...);)
+
+    $(BOOKTABLE Format Specifiers,
+        $(TR $(TH Specifier) $(TH Description))
+        $(TR $(TD $(D %s)) $(TD Default "string" representation (works for most types)))
+        $(TR $(TD $(D %d)) $(TD Signed integer (decimal)))
+        $(TR $(TD $(D %f)) $(TD Floating point))
+        $(TR $(TD $(D %x) / $(D %X)) $(TD Hexadecimal (lowercase / uppercase)))
+        $(TR $(TD $(D %b)) $(TD Binary))
+        $(TR $(TD $(D %(...%))) $(TD Array/Range formatting))
+        $(TR $(TD $(D %?)) $(TD Boolean ($(D true)/$(D false))))
+    )
+
+    $(H2 Alignment and Precision)
+    $(UL
+        $(LI $(B Width:) $(D %10s) pads to 10 characters.)
+        $(LI $(B Alignment:) $(D %-10s) left-aligns.)
+        $(LI $(B Zero-padding:) $(D %05d) pads integers with leading zeros.)
+        $(LI $(B Precision:) $(D %.2f) rounds floats to two decimal places.)
+    )
+
+    $(H2 Indexing and Position)
+    $(P Use $(D pos$) to reference specific arguments:)
+    $(D_CODE writefln("%1$s %2$s %1$s", "A", "B"); // Output: A B A)
+
+    $(H2 Formatting Arrays)
+    $(P Arrays use the $(D %( %)) delimiter:)
+    $(D_CODE
+int[] arr = [1, 2, 3];
+writefln("%(%d, %)", arr); // Output: 1, 2, 3
+writefln("[%-(%d|%)]", arr); // Output: [1|2|3] (hyphen removes trailing delimiter)
+    )
+
+    $(H2 Struct and Class Formatting)
+    $(UL
+        $(LI $(D %s): Calls $(D toString()) if defined, otherwise prints struct members.)
+        $(LI $(D %S): Forces $(D toString()) call.)
+        $(LI $(D %+v): Prints struct field names and values.)
+    )
+
+    $(P $(B See also:) Full documentation in $(MREF std, format).)
+)
+)
+
+Macros:
+    TITLE=Format Logic

posix.mak

@@ -347,7 +347,7 @@ ARTICLE_FILES=$(addprefix articles/, index builtin code_coverage const-faq \
 PAGES_ROOT=$(SPEC_ROOT) 404 acknowledgements areas-of-d-usage $(ARTICLE_FILES) \
 	ascii-table bugstats $(CHANGELOG_FILES) community comparison contributing \
 	deprecate dmd dmd-freebsd dmd-linux dmd-osx dmd-windows \
-	documentation download dstyle forum-template gpg_keys \
+	documentation download dstyle format forum-template gpg_keys \
 	howto-promote htod index install \
 	menu orgs-using-d overview rdmd resources search security tuple wc windbg \
 	$(addprefix foundation/, index about donate prman sponsors upb-scholarship) \