tools/fidl/fidlgen_cpp/codegen/README.md

# Template Organization And Naming

To keep things kind of maintainable here's how templates are named and organized.

## Template source files

All template files are named `.tmpl.go` so that they're recognized by editors
and other tools as Go source files but can be differentiated from Go source
files that implement their logic in Go rather than the template language.

Each `.tmpl.go` file should only contain a single string variable named
similarly to the file. A file named `foo_bar_baz.tmpl.go` will contain a single
variable:
```
const fooBarBaz = `
// actual template code here
`
```

The file should include a comment above the string describing the templates
defined in the variable.

## Template names

Templates are defined with `{{- define "TemplateName" -}} ... {{- end -}}`
where the template name string with two or three parts separated by colons.

The first part of the template is always the type of data it operates on, the
last part of the template is where it can be used and the middle is for
disambiguation.

## File templates

Each file generated by the bindings generator is rooted in a template file
named `file_something.tmpl.go` containing a string variable named
`fileSomething` with a template named `File:Something`. For example the header
template is in the file `file_header.tmpl.go` and contains:
```
const fileHeaderTmpl = `
{{- define "File:Header" -}}
// The header file template
{{ -end }}
```

## Fragment templates

We refer to templates that generate a part of a file as *fragment* templates.
Fragment templates are in files named `fragment_*.tmpl.go`. Fragment templates
are named by the type of object that they operate on. Each fragment template
file contains only fragment templates that operate on a specific object type.

For example all templates that operate on struct objects are in
`fragment_struct.tmpl.go` in a variable called `fragmentStruct` and their names
all begin with `Struct:`.

Templates for some more complex types may be split across multiple files
(and hence variables). They should be logically grouped and still must begin
with the name of the type being operated on. For example
`fragment_protocol_client_impl.tmpl.go` contains the templates for generating a
protocol's `ClientImpl`. There are templates in this file named
`Protocol:ClientImpl:Header` and `Protocol:ClientImpl:Source`

Fragment templates must include the name of the file they should be generated
into as the last part of their name. So the template for generating struct
information into a the header (called from the `File:Header` file template) is
`Struct:Header` and the template for generating the source file (called from the
`File:Source` file template) is `Struct:Source`.

## Helper templates

Some templates generate code that belongs in multiple places. These are helper
templates and instead of having the name of a file as their last part they end
with `:Helper`, for example `Method:ClientAllocationComment:Helper`.

## Integration and build

All template files are listed as `sources` for `gopkg` in
`//tools/fidl/fidlgen_cpp/BUILD.gn`. All template variables are listed
alphabetically in the `templates` variable in the `NewGenerator` function in
`//tools/fidl/fidlgen_cpp/codegen/codegen.go`