package format import ( "reflect" "sort" "strings" ) // MarkdownTreeRenderer renders a ContainerNode tree into a markdown documentation string. type MarkdownTreeRenderer struct { // HeaderPrefix is the prefix string added to section headers (e.g., "## " for H2 headers). HeaderPrefix string // PropsDescription is the introductory text displayed before the query/param properties list. PropsDescription string // PropsEmptyMessage is the message displayed when no query/param properties are available. PropsEmptyMessage string } // Constants for dynamic path segment offsets. // These offsets are added to URLPath to represent dynamic path segments beyond the base path. const ( // PathOffset1 represents the first dynamic path segment (URLPath + 1). PathOffset1 = 1 // PathOffset2 represents the second dynamic path segment (URLPath + 2). PathOffset2 = 2 // PathOffset3 represents the third dynamic path segment (URLPath + 3). PathOffset3 = 3 ) // RenderTree renders a ContainerNode tree into a markdown documentation string. // It categorizes fields into URL fields and query/param fields, sorts them appropriately, // and generates formatted markdown documentation including URL structure and field descriptions. // // Parameters: // - root: The container node tree containing all field information to render. // - scheme: The URL scheme (e.g., "https", "smtp") used when displaying URL field examples. // // Returns a formatted markdown documentation string. func (r MarkdownTreeRenderer) RenderTree(root *ContainerNode, scheme string) string { stringBuilder := strings.Builder{} // Initialize slices to categorize fields by their URL part types. // queryFields holds fields that are query parameters or have no URL parts. queryFields := make([]*FieldInfo, 0, len(root.Items)) // urlFields holds fields that map to standard URL components (user, password, host, port, path). urlFields := make([]*FieldInfo, 0, len(root.Items)) // dynamicURLFields holds fields that map to dynamic path segments (path offsets 1-3). dynamicURLFields := make([]*FieldInfo, 0, len(root.Items)) // Categorize each field based on its URLParts. for _, node := range root.Items { field := node.Field() for _, urlPart := range field.URLParts { switch urlPart { case URLQuery: // Query parameter fields are added to queryFields. queryFields = append(queryFields, field) case URLPath + PathOffset1, URLPath + PathOffset2, URLPath + PathOffset3: // Dynamic path segments are added to dynamicURLFields. dynamicURLFields = append(dynamicURLFields, field) case URLUser, URLPassword, URLHost, URLPort, URLPath: // Standard URL components are added to urlFields. urlFields = append(urlFields, field) } } // Fields with no URL parts default to queryFields. if len(field.URLParts) < 1 { queryFields = append(queryFields, field) } } // Append dynamic fields to urlFields so they appear in the URL section. urlFields = append(urlFields, dynamicURLFields...) // Sort urlFields by their primary URLPart to ensure consistent ordering. // The order follows the URL structure: user, password, host, port, path. sort.SliceStable(urlFields, func(i, j int) bool { urlPartA := URLQuery if len(urlFields[i].URLParts) > 0 { urlPartA = urlFields[i].URLParts[0] } urlPartB := URLQuery if len(urlFields[j].URLParts) > 0 { urlPartB = urlFields[j].URLParts[0] } return urlPartA < urlPartB }) // Generate the URL Fields section. r.writeURLFields(&stringBuilder, urlFields, scheme) // Add blank line between URL Fields section and Query/Param Props section. if len(urlFields) > 0 { stringBuilder.WriteString("\n") } // Sort queryFields to place required fields first, followed by optional fields. sort.SliceStable(queryFields, func(i, j int) bool { return queryFields[i].Required && !queryFields[j].Required }) // Filter out fields without key tags, as they cannot be set via query parameters. keyedFields := make([]*FieldInfo, 0, len(queryFields)) for _, field := range queryFields { if len(field.Keys) > 0 { keyedFields = append(keyedFields, field) } } // Generate the Query/Param Props section header. r.writeHeader(&stringBuilder, "Query/Param Props") // Add either the description or empty message based on whether query fields exist. if len(keyedFields) > 0 { stringBuilder.WriteString(r.PropsDescription) } else { stringBuilder.WriteString(r.PropsEmptyMessage) } // Add a blank line after the description if both exist. if len(keyedFields) > 0 && r.PropsDescription != "" { // If PropsDescription doesn't end with a newline, we need to end the line // and add a blank line (\n\n). If it already ends with a newline, we only // need to add one more for the blank line. if strings.HasSuffix(r.PropsDescription, "\n") { stringBuilder.WriteString("\n") } else { stringBuilder.WriteString("\n\n") } } // Generate documentation for each query field. for i, field := range keyedFields { // Add blank line between fields. if i > 0 { stringBuilder.WriteString("\n") } // Write the primary field information (name, description, required/default). r.writeFieldPrimary(&stringBuilder, field) // Write additional field information (aliases, enum values). r.writeFieldExtras(&stringBuilder, field) } return stringBuilder.String() } // writeFieldExtras writes additional field information including aliases and possible enum values. // // Parameters: // - stringBuilder: The string builder to append the formatted output to. // - field: The field information to extract aliases and enum values from. func (MarkdownTreeRenderer) writeFieldExtras(stringBuilder *strings.Builder, field *FieldInfo) { // Output aliases if the field has more than one key (alternative names). if len(field.Keys) > 1 { stringBuilder.WriteString(" Aliases: `") for i, key := range field.Keys { if i == 0 { // Skip the primary key since it is shown as the field name above. continue } if i > 1 { stringBuilder.WriteString("`, `") } stringBuilder.WriteString(key) } stringBuilder.WriteString("`\n") } // Output possible enum values if the field has an enum formatter. if field.EnumFormatter != nil { stringBuilder.WriteString(" Possible values: `") for i, name := range field.EnumFormatter.Names() { if i != 0 { stringBuilder.WriteString("`, `") } stringBuilder.WriteString(name) } stringBuilder.WriteString("`\n") } } // writeFieldPrimary writes the primary field information including name, description, // required status, and default value. // // Parameters: // - stringBuilder: The string builder to append the formatted output to. // - field: The field information to render. func (MarkdownTreeRenderer) writeFieldPrimary(stringBuilder *strings.Builder, field *FieldInfo) { fieldKey := field.Name if len(field.Keys) > 0 { fieldKey = field.Keys[0] } // Write the field name in bold. stringBuilder.WriteString("* __") stringBuilder.WriteString(fieldKey) stringBuilder.WriteString("__") // Append the field description if available. if field.Description != "" { stringBuilder.WriteString(" - ") stringBuilder.WriteString(field.Description) } // Mark required fields or show the default value for optional fields. if field.Required { stringBuilder.WriteString(" (__Required__)\n") } else { stringBuilder.WriteString("\n Default: ") // Display "*empty*" for fields with no default value. if field.DefaultValue == "" { stringBuilder.WriteString("*empty*") } else { // For boolean fields, prepend a checkmark or xmark based on the value. if field.Type.Kind() == reflect.Bool { defaultValue, _ := ParseBool(field.DefaultValue, false) if defaultValue { stringBuilder.WriteString("✔ ") } else { stringBuilder.WriteString("❌ ") } } // Wrap the default value in backticks for code formatting. stringBuilder.WriteByte('`') stringBuilder.WriteString(field.DefaultValue) stringBuilder.WriteByte('`') } stringBuilder.WriteString("\n") } } // writeHeader writes a section header with the configured prefix. // // Parameters: // - stringBuilder: The string builder to append the formatted header to. // - text: The header text to write. func (r MarkdownTreeRenderer) writeHeader(stringBuilder *strings.Builder, text string) { stringBuilder.WriteString(r.HeaderPrefix) stringBuilder.WriteString(text) stringBuilder.WriteString("\n\n") } // writeURLFields writes the URL Fields section with an example URL for each field. // Each field is highlighted in the context of a complete URL structure. // // Parameters: // - stringBuilder: The string builder to append the formatted output to. // - urlFields: The list of fields that are part of the URL. // - scheme: The URL scheme to use in the example URLs. func (r MarkdownTreeRenderer) writeURLFields( stringBuilder *strings.Builder, urlFields []*FieldInfo, scheme string, ) { // Track which fields have been printed to avoid duplicates. fieldsPrinted := make(map[string]bool) // Write the section header. r.writeHeader(stringBuilder, "URL Fields") // Generate documentation for each unique URL field. for _, field := range urlFields { // Skip nil fields and fields that have already been processed. if field == nil || fieldsPrinted[field.Name] { continue } // Write the primary field information. r.writeFieldPrimary(stringBuilder, field) // Write the URL example on a new line within the same list item. stringBuilder.WriteString("
URL part: ") stringBuilder.WriteString(scheme) stringBuilder.WriteString("://") // Detect the presence of user and password fields for proper URL formatting. hasUser := false hasPassword := false // Track the highest URLPart to determine if trailing slash is needed. maxPart := URLUser for _, f := range urlFields { if f != nil { for _, part := range f.URLParts { switch part { case URLQuery, URLHost, URLPort, URLPath: // No-op for these cases. case URLUser: hasUser = true case URLPassword: hasPassword = true } // Update the maximum URLPart encountered. if part > maxPart { maxPart = part } } } } // Build the URL with the current field highlighted. // Iterate through all possible URL parts to construct the complete URL structure. for i := URLUser; i <= URLPath+PathOffset3; i++ { for _, fieldInfo := range urlFields { // Skip fields that don't correspond to the current URL part. if fieldInfo == nil || !fieldInfo.IsURLPart(i) { continue } // Add the appropriate separator between URL components. if i > URLUser { lastPart := i - 1 if lastPart == URLPassword && (hasUser || hasPassword) { // Add ':' separator only if credentials are present. stringBuilder.WriteRune(lastPart.Suffix()) } else if lastPart != URLPassword { // Add standard separators like '/' or '@'. stringBuilder.WriteRune(lastPart.Suffix()) } } // Convert the field name to lowercase for the URL example. slug := strings.ToLower(fieldInfo.Name) // Special case: when displaying port, use "port" as the label. if slug == "host" && i == URLPort { slug = "port" } // Highlight the current field with bold HTML tags. if fieldInfo == field { stringBuilder.WriteString("") stringBuilder.WriteString(slug) stringBuilder.WriteString("") } else { stringBuilder.WriteString(slug) } break } } // Add trailing '/' if no dynamic path segments follow the base path. if maxPart < URLPath+PathOffset1 { stringBuilder.WriteByte('/') } stringBuilder.WriteString("\n") // Mark this field as printed to avoid duplicates. fieldsPrinted[field.Name] = true } }