tools/cppdocgen/docgen/write_define.go

// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

package docgen

import (
	"fmt"
	"io"
)

// Interface for sorting the record list by function name.
type defineByName []*Define

func (f defineByName) Len() int {
	return len(f)
}
func (f defineByName) Swap(i, j int) {
	f[i], f[j] = f[j], f[i]
}
func (f defineByName) Less(i, j int) bool {
	return f[i].Name < f[j].Name
}

func writeDefineGroupSection(settings WriteSettings, index *Index, g *DefineGroup, f io.Writer) {
	// Devsite uses {:#htmlId} to give the title a custom ID.
	htmlId := defineGroupHtmlId(*g)
	if len(g.ExplicitTitle) != 0 {
		fmt.Fprintf(f, "## %s {:#%s}\n\n", g.ExplicitTitle, htmlId)
	} else if len(g.Defines[0].ParamString) == 0 {
		fmt.Fprintf(f, "## %s macro {:#%s}\n\n", g.Defines[0].Name, htmlId)
	} else if g.Defines[0].ParamString == "()" {
		fmt.Fprintf(f, "## %s() macro {:#%s}\n\n", g.Defines[0].Name, htmlId)
	} else {
		fmt.Fprintf(f, "## %s(…) macro {:#%s}\n\n", g.Defines[0].Name, htmlId)
	}

	fmt.Fprintf(f, "[Declaration source code](%s)\n\n",
		settings.locationSourceLink(g.Defines[0].Location))

	if !commentContains(g.Defines[0].Description, NoDeclTag) {
		writeDefineDeclarationBlock(g.Defines, f)
	}

	// If the comment has a heading, it will have been extracted and used as the title so we
	// need to strip that to avoid duplicating.
	_, commentWithNoH1 := extractCommentHeading1(g.Defines[0].Description)
	writeComment(index, commentWithNoH1, markdownHeading2, f)
	fmt.Fprintf(f, "\n")
}

func defineHtmlId(d Define) string {
	// Use the define name as the ID (may need changing in the future).
	return d.Name
}

func defineGroupHtmlId(g DefineGroup) string {
	// Devsite only supports one ID per heading, so just use the first.
	return defineHtmlId(*g.Defines[0])
}

// This assumes the define destination will exist.
func defineLink(d Define) string {
	return HeaderReferenceFile(d.Location.Filename) + "#" + defineHtmlId(d)
}

func defineGroupLink(g DefineGroup) string {
	return HeaderReferenceFile(g.Defines[0].Location.Filename) + "#" + defineGroupHtmlId(g)
}

func writeDefineDeclarationBlock(defines []*Define, f io.Writer) {
	writePreHeader(f)

	for _, d := range defines {
		fmt.Fprintf(f, "<span class=\"kwd\">#define</span> <span class=\"lit\">%s</span>", d.Name)
		if len(d.ParamString) > 0 {
			fmt.Fprintf(f, "%s", d.ParamString)
		}

		if len(d.Value) > 0 {
			if d.Value[len(d.Value)-1] == byte('\\') {
				// A multiline macro definition, replace the "\" with "...".
				fmt.Fprintf(f, " %s...\n", d.Value[:len(d.Value)-1])
			} else {
				fmt.Fprintf(f, " %s\n", d.Value)
			}
		}
	}

	writePreFooter(f)
}