docs: document FormatterOption and opts param; test: add --raw-errors long-form case

Author: dlevy-msft-sql

cmd/sqlcmd/sqlcmd_test.go

@@ -126,6 +126,9 @@ func TestValidCommandLineToArgsConversion(t *testing.T) {
 		{[]string{"-j"}, func(args SQLCmdArguments) bool {
 			return args.RawErrors
 		}},
+		{[]string{"--raw-errors"}, func(args SQLCmdArguments) bool {
+			return args.RawErrors
+		}},
 	}
 
 	for _, test := range commands {

pkg/sqlcmd/format.go

@@ -88,7 +88,8 @@ type sqlCmdFormatterType struct {
 	rawErrors            bool
 }
 
-// FormatterOption configures a Formatter returned by NewSQLCmdDefaultFormatter.
+// FormatterOption customizes the default formatter built by NewSQLCmdDefaultFormatter.
+// Use the provided With* constructors (e.g. WithRawErrors) to supply options.
 type FormatterOption func(*sqlCmdFormatterType)
 
 // WithRawErrors controls AddError prefix handling: when raw is true, AddError
@@ -100,7 +101,7 @@ func WithRawErrors(raw bool) FormatterOption {
 
 // NewSQLCmdDefaultFormatter returns a Formatter based on the configuration.
 // It returns an ASCII formatter if the format is set to "ascii", otherwise it returns a formatter that mimics the original ODBC-based sqlcmd formatter.
-// FormatterOption values (e.g. WithRawErrors) apply only to the ODBC-mimicking formatter; the ASCII formatter ignores them.
+// Any FormatterOption values passed via opts (e.g. WithRawErrors) are applied to the ODBC-mimicking formatter; the ASCII formatter ignores them.
 func NewSQLCmdDefaultFormatter(vars *Variables, removeTrailingSpaces bool, ccb ControlCharacterBehavior, opts ...FormatterOption) Formatter {
 	if vars.Format() == "ascii" {
 		return NewSQLCmdAsciiFormatter(vars, removeTrailingSpaces, ccb)