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
@@ -98,7 +99,8 @@ func WithRawErrors(raw bool) FormatterOption {
 	return func(f *sqlCmdFormatterType) { f.rawErrors = raw }
 }
 
-// NewSQLCmdDefaultFormatter returns a Formatter that mimics the original ODBC-based sqlcmd formatter
+// NewSQLCmdDefaultFormatter returns a Formatter that mimics the original ODBC-based sqlcmd formatter.
+// Any FormatterOption values passed via opts (e.g. WithRawErrors) are applied to the new formatter.
 func NewSQLCmdDefaultFormatter(removeTrailingSpaces bool, ccb ControlCharacterBehavior, opts ...FormatterOption) Formatter {
 	f := &sqlCmdFormatterType{
 		removeTrailingSpaces: removeTrailingSpaces,