| # 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` |