Vulkan-Docs/doc/specs/vulkan/style/styleguide.txt

// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html

Vulkan Style Guide
==================
Jon Leech
include::../specversion.txt[]
:toc2:
:toclevels: 3
:max-width: 100
:numbered:
:doctype: book
:imagewidth: 800
:fullimagewidth: {svgpdf@pdf:scaledwidth="75%":width="800"}
:cl: :

:leveloffset: 1

// :icons:
// :toc-placement: manual

<<<<

include::../copyright.txt[]

<<<<

[[introduction]]
= Introduction

This is the Vulkan Documentation Style Guide, containing the collected
rules, guidelines, tricks, and tips for authors contributing to the Vulkan
API Specification (the _Specification_), reference pages, and other
documentation such as white papers and tutorials (if and when we have them).
These are collectively referred to as _Vulkan Documentation_ or just
_documentation_ below. The primary focus and inspiration is the
Specification, although all of the markup and most of the writing style is
equally applicable to the reference pages.

The primary purpose of the style guide is to achieve consistency of both
source and output documents. Consistency makes it easier for editors,
reviewers, and users of our documentation to understand and modify it. When
the style guide makes prescriptive statements, please follow them unless
there are compelling reasons not to. If you have a strong desire to change
these guidelines, you can try to make a case starting with the Specification
editors, and proceeding to the Vulkan Working Group if need be.

[NOTE]
.Note
====
But be prepared to make the numerous merge requests applying those changes
to all parts of our documentation, if your change request is accepted!
====

The style guide is broken into two major sections:

  * <<markup,Markup Style>> - how to write asciidoc and XML source that
    follows consistent formatting and layout guidelines, tags special terms
    and phrases for proper processing by the spec generation tools, etc.
  * <<writing,Writing Style>> - overall and fine-grained structure and
    conventions, normative language use, API naming conventions, common
    words and phrases to use (and those not to use), linking and
    cross-referencing, etc.


[[introduction-asciidoc]]
== Asciidoc Markup

Vulkan Documentation is primarily written in Asciidoc, a form of text markup
language. Asciidoc is documented on its website at http://www.asciidoc.org/.

[[userguide]]
References to the Asciidoc User Guide are to sections in the document at
http://asciidoc.org/userguide.html .

Asciidoc packages are available for Linux, MacOS, and Microsoft Windows,
together with the other toolchain components required to generate output
documents corresponding to the markup. Note that we are currently using the
original _asciidoc_ tool. Other tools to process Asciidoc markup, such as
_asciidoctor_, are also available, but are not currently usable for our
documents. While asciidoctor supports the basic Asciidoc markup syntax, it
does not support asciidoc macros, which are used extensively in the
documentation. It is possible to move from asciidoc to asciidoctor, but this
will be a significant effort, taking place after Vulkan 1.0 is published.

This guide does not address the toolchain and build process, just source
documents.


[[markup]]
= Markup Style

This chapter demonstrates Asciidoc and Specification structure, including
text layout and markup style.

Chapters and sections follow a rigid template consisting of an optional
anchor (if other parts of the document cross-reference the section) followed
by a one line title (see section 11.2 of the <<userguide,User Guide>>) and a
blank line. The anchor is typically the base name of the file containing the
chapter, with a lowercased version of the section name following, with
spaces replaced by dashes.

Always use the one-line title form, with one to five = signs preceding the
chapter/section title. The two-line title form cannot be easily searched for
and often looks like other types of asciidoc delimiters.

Always precede the anchor by two blank lines (except at the beginning of a
file), and follow the title by a blank line, to set off sections visibly.

.Example Markup
----
[[markup]]
= Markup Style


[[markup-sample-section]]
== Sample Section
----


[[markup-sample-section]]
== Sample Section

This is a sample section of the Vulkan Specification, nested one level
inside a chapter. Sections can be nested up to level 5, although not all
levels are included in the Table of Contents.


[[markup-layout]]
== Layout, Line Lengths, and Lists

Asciidoc source should be text filled to 76 columns with hard line breaks.
Except when necessary for lists or other markup, text should begin at the
first column of each line (leading spaces are often semantically meaningful
in asciidoc markup).

UTF-8 characters outside the ASCII subset should be used sparingly, only
when needed for non-English names. Instead use asciidoc markup for special
characters, if required. For example, two hyphens produces an en-dash:

[NOTE]
.Example Markup
====

`An -- en-dash` -> An -- en-dash
====

As an exception, multiplication should be marked with the unicode
multiplication symbol ``×'' (and *not* an asterisk) when used in plain
text. In math sections, the same symbol should be referred to as `\times`.
In code sections, a conventional asterisk (`*`) should be used instead.

See chapter 10 of the <<userguide,User Guide>> for supported special
characters, as well as use of entity references.

Quotation marks should use the 66/99 convention. That is, double asymmetric
quotation marks, indicated by double back-ticks as opening marks and double
apostrophes as closing marks (\`\`like this''), which renders ``like this''.

_Never_ use hard tabs or trailing blanks.

* In some cases, limitations of asciidoc markup may result in lines that are
  longer than 76 characters and cannot easily be shortened without
  compromising the output documents.


[[markup-samplesection-lists]]
=== Lists

  * Bullet lists are the preferred form of list, aside from glossary
    definitions.
  * Lists should have text indented by 4 spaces and the list item delimiter
    (e.g. one or more asterisks, for bullet lists) indented by two spaces.
+
--
Note that continuation blocks for list items longer than one paragraph
cannot be indented, only the first paragraph.

In general, successive list items should not be separated by white space.
However, list continuation blocks must be followed by a blank line due to
limitations of the asciidoc parser.
--

  * Indent bullet lists two spaces (to the bullet), 4 spaces (to the text,
    if it extends over multiple lines). This lets us visually distinguish
    lists from other kinds of markup.
  ** Nested lists should align the leftmost list item delimiter (bullet,
     etc.) with the parent delimiter.

.Example Markup
----
  * This is the first item in a bullet list.
  * The second item is described with two paragraphs. The second
    paragraph is in a continuation block:
+
--
This is the second paragraph.
--

  ** This is a nested list item for the second item. Since it
     follows a continuation block, it must be separated by a
     blank line from that block.
----


[[markup-samplesection-anchors]]
=== Anchors and Cross-references

In general, chapters and sections should always have anchors, following the
naming convention <<markup,discussed above>>. Anchors to other sections of
the document may be inserted as needed. In addition, the autogenerated
include files defining commands, structures, enumerations and flags all
define anchors whose name is the name of the command or type being defined,
so it's easy to link to a (for example) a command name such as
<<vkCreateCommandPool>>.

If you want a cross-reference to an anchor to appear as something other than
the raw anchor name, always make sure to include that text as part of the
cross-reference. There are several different toolchains followed for various
forms of asciidoc output, and not all of them treat anchors without alt-text
the same way.

.Example Markup
----
In general, chapters and sections should always have anchors,
following the naming convention <<markup,discussed above>>.
Link to a command name such as <<vkCreateCommandPool>>.
----


[[markup-markup]]
== Markup Macros and Normative Terminology

This section discusses Asciidoc macros used in the document. In addition to
the macros defined by asciidoc itself, additional macros are defined by the
Specification and Reference Page configuration files.


=== API Markup Macros

These macros must: be used to tag command, structure, enumeration,
enumerant, and other Vulkan-specific names so they can be rendered in a
distinctive fashion, link to definitions of those names, and be easily
searched for in the source documents. The validation scripts (`make
allchecks` output) also rely on these macros being used consistently and
correctly. The API markup macros, with examples of their use, are in the
following table:

.API Markup Macros
[width="100%",options="header",cols="20%,80%"]
|=====
| Macro Name    | Usage and Meaning
| flink{cl}     | Generates a cross-reference or link to the definition of
                  the command name in the macro argument. Example:
                  flink{cl}vkCreateCommandPool -> flink:vkCreateCommandPool.
| fname{cl}     | Formats the macro argument like flink{cl}. Does not
                  generate a cross-reference. Example:
                  fname{cl}vkCreateCommandPool -> fname:vkCreateCommandPool.
                  The flink{cl} macro is preferred.
| ftext{cl}     | Formats the macro argument like fname{cl}. May contain
                  asterisks for wildcards. Not validated. Example:
                  ftext{cl}vkCmd* -> ftext:vkCmd*.

                  Only use ftext{cl} when it is necessary to describe
                  something that should be rendered like a command name,
                  but is not actually one (e.g. is a wildcard or subset of
                  an actual command name).
| slink{cl}     | Generates a cross-reference or link to the definition
                  of the structure in the macro argument. Example:
                  slink{cl}VkCommandPoolCreateInfo ->
                  slink:VkCommandPoolCreateInfo.
| sname{cl}     | Formats the macro argument like slink{cl}. Does not
                  generate a cross-reference. May also be an abstract
                  structure or handle name. Example:
                  sname{cl}VkCommandPoolCreateInfo ->
                  sname:VkCommandPoolCreateInfo. The slink{cl} macro is
                  preferred if a definition of the target type with an
                  anchor exists in the document.
| stext{cl}     | Formats the macro argument like sname{cl}. May contain
                  asterisks for wildcards. Not validated. Example:
                  stext{cl}Vk*CreateInfo -> stext:Vk*CreateInfo.

                  Only use stext{cl} when it is necessary to describe
                  something that should be rendered like a structure name,
                  but is not actually one (e.g. is a wildcard or subset of
                  an actual structure name).
| elink{cl}     | Formats the macro argument as a Vulkan enumeration
                  name and links to the definition of that enumeration type.
                  Example: ename{cl}VkResult -> ename:VkResult.
| ename{cl}     | Formats the macro argument as a Vulkan enumerant name.
                  Example: ename{cl}VK_EVENT_SET -> ename:VK_EVENT_SET.
| etext{cl}     | Formats the macro argument like ename{cl}. Not validated.
                  Examples: etext{cl}_RANGE_SIZE -> etext:_RANGE_SIZE,
                  etext{cl}VK_IMAGE_CREATE_SPARSE_* ->
                  etext:VK_IMAGE_CREATE_SPARSE_*

                  Only use stext{cl} when it is necessary to describe
                  something that should be rendered like a enumerant name,
                  but is not actually one (e.g. is a wildcard or subset of
                  an actual enumerant name).
| pname{cl}     | Formats the macro argument as a Vulkan parameter or
                  structure member name. Example: pname{cl}device ->
                  pname:device.
| ptext{cl}     | Formats the macro argument like pname{cl}. May contain
                  asterisks for wildcards. Not validated. Example:
                  ptext{cl}sparseResidency* -> ptext:sparseResidency*.

                  Only use ptext{cl} when it is necessary to describe
                  something that should be rendered like a parameter name,
                  but is not actually one (e.g. is a wildcard or subset of
                  an actual parameter name).
| tlink{cl}     | Generates a cross-reference or link to the definition
                  of the Vulkan type in the macro argument. Example:
                  tlink{cl}PFN_vkAllocationFunction ->
                  tlink:PFN_vkAllocationFunction. This is only used for
                  function pointer types at present.
| tname{cl}     | Formats the macro argument like tlink{cl}. Does not
                  generate a cross-reference. Example:
                  tname{cl}PFN_vkAllocationFunction ->
                  tname:PFN_vkAllocationFunction. The tlink{cl} macro is
                  preferred.
| basetype{cl}  | Formats the macro argument like a basic scalar type
                  or API handle name. Not validated. Examples:
                  basetype{cl}uint32_t -> basetype:uint32_t,
                  basetype{cl}VkDeviceSize -> basetype:VkDeviceSize.
| code{cl}      | Formats the macro argument as a code sample. Primarily
                  used for SPIR-V keywords. Examples: code{cl}ClipDistance
                  -> code:ClipDistance, code{cl}VK_NULL_HANDLE ->
                  code:VK_NULL_HANDLE, code{cl}NULL -> code:NULL.
|=====


==== Other Markup

Uses of standard Asciidoc markup are less common. Occasional asterisk markup
is used for *emphasis*. Backtick markup is sometimes used for the C `NULL`
macro, but the code{cl} macro should be used for code:NULL instead.

.Example Markup
----
*emphasis*
`NULL`
code:NULL
----


==== Glossary Terms

_Glossary terms_ are currently marked up using underscore markup where they
are defined in the documents, as well as being added to the formal Glossary
appendix in the Specification. However, we will probably change to using
custom macros soon, to enable linkage between the glossary appendix and
definitions in the spec body.

.Example Markup
----
_Glossary terms_
----


=== Normative Terminology

Normative terminology is precisely defined in section 1.3 of the Vulkan API
Specification, and is used to visually tag terms which express mandatory and
optional behavior of Vulkan implementations, and of applications using
Vulkan.

Whenever one of these terms appears in the Specification, it must: be tagged
using the macros, to indicate that its use has been carefully considered and
is consistent with the definitions in section 1.3. This is extremely
important for determining IP that is in and out of Scope during Ratification
reviews. The normative terminology macros are defined in the following
table:

.Normative Terminology Macros
[width="100%",options="header"]
|=====
| Macro Name     | Meaning
| can{cl}        | can:
| cannot{cl}     | cannot:
| may{cl}        | may:
| must{cl}       | must:
| mustnot{cl}    | mustnot:
| optional{cl}   | optional:
| optionally{cl} | optionally:
| recommend{cl}  | recommend:
| required{cl}   | required:
| should{cl}     | should:
| shouldnot{cl}  | shouldnot:
|=====

Because asciidoc macro names cannot contain spaces, macros which correspond
to multiple words (mustnot{cl}, and shouldnot{cl}) drop those spaces. Also
note that the macros are lower-case only, so language should be written such
that these terms do not appear at the beginning of a sentence (if really
necessary, additional capitalized macros could be added).


==== Optional Behavior

If a described behavior of the implementation is not necessary for
conformance, use the terms _may:_ or _optional:_ to describe it.

If a described usage pattern by the application is allowed but
not necessary, use the term _can:_ to describe it.

If language flows more logically using the term "may not", use the term
_may: not_ to describe it.


==== Optional Functionality

If functionality (rather than behavior) is optional, it should be
described as

.Example Markup
----
not required:
----

Implementations are not mandated to support functionality which is not
required:, but if they do, they must: behave as described by the
Specification. The term _functionality_ includes API features, extensions,
and layers.


[[markup-informative]]
== Informative, Editing and Implementor's Notes

There are several possible types of notes. Depending on the type of output,
they are rendered in different styles, but always include a note title, and
are usually set off in a box or with an icon. While asciidoc supports a wide
set of _admonition paragraphs_ such as TIP, IMPORTANT, WARNING, and CAUTION,
we always use the NOTE form, augmented by a note title. Each type of note is
discussed below.


[[markup-informative-notes]]
=== Informative Notes

Informative notes always appear as part of the document, but are considered
non-normative. They usually describe usage advice for applications, and are
always given the title _Note_, as in the following example:

[NOTE]
.Note
====
This is an informative note.
====

.Example Markup
----
[NOTE]
.Note
====
This is an informative note.
====
----

If an entire chapter or section is considered informative, it should begin
with the sentence:

.Example Markup
----
This chapter/section is Informative.
----


=== Editing Notes

Editing notes only appear in internal (non-published) versions of documents,
via asciidoc conditionals, and should be removed from the source before
pushing content to a canonical (master or per-extension) public repository.
They usually tag places where an outstanding bug or Gitlab/Github issue is
being worked, and are always given the title _editing-note_, as in the
following example:

ifdef::editing-notes[]
[NOTE]
.editing-note
====
This is an editing note, marked up as follows:
====
endif::editing-notes[]

.Example Markup
----
\ifdef::editing-notes[]
[NOTE]
.editing-note
====
Contents of an editing note go here. It is good practice to include a
bug/issue number, or link to the bug/issue, in the editing note.
====
\endif::editing-notes[]
----


=== Implementor's Notes

Implementor's notes may or may not appear in published versions of
documents, via asciidoc conditionals. They describe suggested approaches or
guidelines for people writing Vulkan implementations, and are rare because
the hardware being targeted varies so widely. They are always given the
title _Implementor's Note_, as in the following example:

ifdef::implementation-guide[]
.Implementor's Note
====
This is an implementor's note, marked up as follows:
====
endif::implementation-guide[]

.Example Markup
----
\ifdef::implementation-guide[]
.Implementor's Note
====
Contents of an implementor's note go here.
====
\endif::implementation-guide[]
----


== Word Choices

There are a variety of common terms that have several equivalent word
choices. Always use the words in the first column instead of the alternate
terms. This list may not be comprehensive; when in doubt, be guided by the
existing API Specification.

.Word Choices
[width="100%",options="header"]
|=====
| Use This      | Instead Of     | Comments
| allocate      | create
                | When describing objects or memory resulting from
                  ftext:vkAllocate* commands.
| application   | client         |
| command       | function
                | Except when talking about function pointers returned by
                  ftext:vkGet*ProcAddr commands.
| create        | allocate
                | When describing objects resulting from ftext:vkCreate*
                  commands.
| depth/stencil | packed (interleaved, combined, _other prefix_)
                  depth/stencil, depth-stencil, DepthStencil, etc.
                | Combined format implicit in the name.
| device        | GPU
                | Implementations on non-GPU devices are possible.
| heterogeneous | heterogenous   | More common
| homogeneous   | homogenous     | More common
| host endianness | platform endianness |
| image subresource | subresource
                | Except when referring to *host-accessible subresources*
| implementation| system         |
| indices       | indexes        | More common
| it is         | it's           | In general, avoid contractions.
| member        | field          |
| pname:parameter are/is
                | pname:parameter specifies (denotes, indicates)
                | In rare cases when _are_ or _if_ are not grammatically
                  appropriate, _specifies_ may be used instead.
| pname:parameter is
                | the value of pname:parameter is
                | In rare cases, _the value of_ is appropriate. See the
                  existing specification language for examples.
| begins / begun      | starts / started | For ftext:vkBegin* - also see ``finish''
| finishes / finished | ends / ended     | For ftext:vkEnd* - also see ``begins''
| used          | referenced     | When describing attachments specified in a
                                   subpass description.
| statically used | referenced   | When describing resources or push constants
                                   accessed by shader code
| a more specific term | referenced | For all other situations.
| component     | channel        | Specifically this refers to color channels/components
|=====

[NOTE]
.Note
====
The ``begin/start'' and ``end/finish'' distinction is still being sorted out.
See Gitlab issue #61.
====


=== Terms to Use With Caution

The term _subset_ is sometimes used to refer to a _strict subset_, and
sometimes used to refer to a subset which may be equal to the entire set.
This is particularly likely to come up when describing bitmasks. Make sure
to use either _subset_ or _strict subset_ as appropriate.

=== Terms to Avoid

Don't describe anything in the documentation using vague or wishy-washy
terms. Our goal is to precisely describe behavior of implementations.

The normative terms may:, optional:, and should: are available when
implementations may make choices of behavior, but when such choices are
allowed, each choice still must: have well-defined behavior.

.Terms to Avoid
[width="100%",options="header"]
|=====
| Bad Term | Comments
| expect   | And variants such as _expected_
| likely   | And variants such as _will likely_
| allowed, could, generally, might, probably, perhaps
           | And all other such terms of choice. Use _may:_ or _can:_
             depending on the context.
| may: or may: not   | Just use _may:_.
|=====


[[writingstyle]]
= Writing Style


[[writingstyle-misc]]
== Miscellaneous Grammar, Spelling, and Punctuation Issues

=== Use the Oxford Comma (Serial Comma)

When writing a sentence listing a series of items, include a comma before
the ``and'' separating the last item.

*Correct:* The red, green, blue, and alpha components.

*Incorrect:* The red, green, blue and alpha components.

Also see http://blog.oxforddictionaries.com/2011/06/oxford-comma/

=== Numbers in Text

When describing the need for a small number of objects, smaller than ten, spell
the number out (e.g. ``one''). If you are describing a literal value that is a
small number, you may use a numeric value (e.g. ``1'').

For example, instead of writing that a bitfield ``contains 1 or more bits'',
write that it ``contains one or more bits''. A counter example is that it is okay
to write ``For non-stereoscopic-3D applications, this value is 1.''


=== Use American Spelling Conventions

In case of conflict, use American rather than British spelling
conventions. For example:

*Correct:* color, signaled.

*Incorrect:* colour, signalled.


[[writingstyle-describing]]
== Describing Commands and Parameters

The Specification describes API commands followed by descriptions of their
parameters, which are usually simple scalar types, handles or pointers to
Vulkan objects or arrays of objects, or structures containing combinations
of scalar types and objects. The templates and examples shown and annotated
here are based on the Specification. Do not vary from them without
compelling need.

Normative parts of the Specification should describe _what_ something does,
rather than _how_ or _why_ an application would want to use it.

[NOTE]
.Guideline
====
As a simple example, say

``To create a command pool, call fname:vkCreateCommandPool''

rather than

``You/The application/The user can create a command pool by calling
fname:vkCreateCommandPool''.

====

Explanations of _why_ and _how_ should largely be confined to reference
documentation, sample code, tutorials, and other such documents. Occasional
non-normative explanations can be included in the Specification using
<<markup-informative-notes,informative notes>>.


[[writingstyle-latexmath]]
== LaTeX Math Markup

There is a considerable amount of math in the documentation, ranging from
simple arithmetic expressions to complicated conditionals. For the most
part, math is marked up using LaTeX math notation, which is either passed
through to the Mathjax browser renderer for HTML outputs, or passed through
to LaTeX for PDF outputs. For some very simple math expressions, asciidoc
markup can be used.

[NOTE]
.Note
====
We still haven't got the latexmath vs. asciidoc font situation sorted out
for all target output forms, so there can be some visual inconsistencies.
====

While LaTeX math macros, including the amsmath package, are supported,
general LaTeX constructs are not.

_Inline math_ is encoded using the latexmath{cl} macro. For example:

  * latexmath:[$[0,1\]$]
  * latexmath:[$x \cdot 0 = 0 \cdot x = 0$]
  * latexmath:[${\textbf c} = t {\textbf c}_1 + (1-t){\textbf c}_2. $]

.Example Markup
----
    latexmath:[$[0,1\]$]
    latexmath:[$x \cdot 0 = 0 \cdot x = 0$]
    latexmath:[${\textbf c} = t {\textbf c}_1 + (1-t){\textbf c}_2. $]
----

Note the escaped bracket in markup for the first expression, which is
necessary to work around asciidoc macro parsing:


_Block math_ is used for more complex equations. This example uses the
amsmath `align*` macros to delimit the expression:

[latexmath]
+++++++++++++++++++
\begin{align*}
c_{RGB} & =
  \begin{cases}
    \frac{c_{sRGB}}{12.92}                              & \textrm{for } c_{sRGB} \leq 0.04045 \\
    \left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \textrm{for } c_{sRGB} > 0.04045
  \end{cases}
\end{align*}
+++++++++++++++++++

.Example Markup
----
[latexmath]
+++++++++++++++++++
\begin{align*}
c_{RGB} & =
  \begin{cases}
    \frac{c_{sRGB}}{12.92}                              & \textrm{for } c_{sRGB} \leq 0.04045 \\
    \left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \textrm{for } c_{sRGB} > 0.04045
  \end{cases}
\end{align*}
+++++++++++++++++++
----

This example uses normal LaTeX math brackets to delimit the expression:

[latexmath]
+++++++++++++++++++
\[
V =
  \begin{cases}
    (-1)^S \times 0.0,                      & E = 0, M = 0     \\
    (-1)^S \times 2^{-14} \times { M \over 2^{10} },
                                            & E = 0,  M \neq 0 \\
    (-1)^S \times 2^{E-15} \times { \left( 1 + { M \over 2^{10} } \right) },
                                            & 0 < E < 31       \\
    (-1)^S \times Inf,             & E = 31, M = 0             \\
    NaN,                           & E = 31, M \neq 0
  \end{cases}
\]
+++++++++++++++++++

.Example Markup
----
[latexmath]
+++++++++++++++++++
\[
V =
  \begin{cases}
    (-1)^S \times 0.0,                      & E = 0, M = 0     \\
    (-1)^S \times 2^{-14} \times { M \over 2^{10} },
                                            & E = 0,  M \neq 0 \\
    (-1)^S \times 2^{E-15} \times { \left( 1 + { M \over 2^{10} } \right) },
                                            & 0 < E < 31       \\
    (-1)^S \times Inf,             & E = 31, M = 0             \\
    NaN,                           & E = 31, M \neq 0
  \end{cases}
\]
+++++++++++++++++++
----


[[writingstyle-example]]
== An Example Command Description

The <<sample-command,next section>> is a sample based on the Specification,
and describes a command in enough detail to see the different usage patterns
and layout / markup used. Informative notes discussing markup and guidelines
are interspersed with the example description to explain how and why it
looks as it does.


[[sample-command]]
== Sample Command Description: Creating Command Pools

To create a command pool, call:

[NOTE]
.Guideline
====
Use a short, active sentence when describing what commands do, instead of
more passive phrasing like ``A command pool is created by calling:'' or ``The
application may create a command pool by calling:''.
====

include::../protos/vkCreateCommandPool.txt[]

[NOTE]
.Guideline
====
After the description, include the autogenerated prototype for the command
from the `../protos/` directory:

    include::../protos/vkCreateCommandPool.txt[]

Note that each autogenerated command, enumeration, flag, or structure
definition include file also defines a corresponding asciidoc anchor which
is the base name of the file. In this case, the anchor is named
`vkCreateCommandPool`.
====

  * pname:device is the logical device that the command pool is created on.
  * pname:pCreateInfo points to an instance of the
    slink:VkCommandPoolCreateInfo structure containing information used to
    create the command pool.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.
  * pname:pCommandPool points to a handle in which the created command pool
    object is returned.

[NOTE]
.Guideline
====
Each command parameter is described in a separate bullet list entry,
followed by validity rules, then detailed descriptions of any new
structures, flags, or enumerations introduced by this command.

Each parameter should appear as a separate bullet list item beginning with
the parameter name, in the same order as parameters appear in the command.
This aids in extracting short descriptions of parameters for inclusion in
annotated headers and similar documentation. Make sure to tag each parameter
with the pname{cl} macro.

Strive for compact notation, and in particular always try to use the
phrasing ``pname{cl}param _is_'' rather than wordier forms such as
``pname{cl}param _specifies_'' or ``The pname{cl}param parameter specifies''. In
general there is no need to describe a parameter which is a Vulkan object
handle *as* a handle; for example, say ``pname{cl}device is the logical
device'' rather than ``pname{cl}device is a handle to the logical device''. An
exception is object creation functions, where a pointer to a handle of the
proper type is used to return the newly created object.
====

include::../validity/protos/vkCreateCommandPool.txt[]

[NOTE]
.Guideline
====
Parameter and member validation language for commands and structures is also
autogenerated from vk.xml, and included from the `../validity/` directories:

    include::../validity/protos/vkCreateCommandPool.txt[]
====

The sname:VkCommandPoolCreateInfo structure is defined as:

include::../structs/VkCommandPoolCreateInfo.txt[]

[NOTE]
.Guideline
====
Structures and enumerations first used as parameters of a command are
described next, by including the autogenerated interface file for that
structure or enumeration:

    include::../structs/VkCommandPoolCreateInfo.txt[]

====

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:flags is a combination of bitfield flags indicating usage behavior
    for the pool and command buffers allocated from it. Possible values
    include:
+
--
include::../enums/VkCommandPoolCreateFlagBits.txt[]

** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT indicates that command buffers
   allocated from the pool will be short-lived.
** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT controls whether
   command buffers allocated from the pool can: be individually reset.
--
  * pname:queueFamilyIndex designates a queue family. Command buffers in
    this command pool must: be submitted on queues from the same family.

[NOTE]
.Guideline
====
Each structure member is described in a separate bullet list entry. For the
stext:Vk*CreateInfo structures in particular, there is standard boilerplate
for the pname:sType and pname:pNext members, followed by the members
specific to the structure.

----
  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an
    extension-specific structure.
----

In some cases, such as when the type of a member is itself a new type, the
entry will cover multiple paragraphs. In these cases the normal list nesting
and indentation guidelines cannot be applied due to limitations of the
asciidoc parser. It is usually best to append a block following the first
paragraph of such a list item:

----
  * pname:flags is a combination of bitfield flags
    indicating usage behavior for the pool and
    command buffers allocated from it. Possible
    values include:
+
--
\include::../enums/VkCommandPoolCreateFlagBits.txt[]

** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT
   indicates that command buffers allocated
   from the pool will be short-lived.
** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT
   controls whether command buffers allocated from
   the pool can: be individually reset.
--
----
====

include::../validity/structs/VkCommandPoolCreateInfo.txt[]

[NOTE]
.Guideline
====
Following the definition of structure members, include the validity language
for this structure:

    include::../validity/structs/VkCommandPoolCreateInfo.txt[]
====


// = API Naming Conventions
//
// It's not clear these belong in this document. They are currently
// captured in the member Wiki under API_Design/Cleanup
//
// If they do go here, we would discuss naming conventions starting with
// prefixes, camelCase, suffixes for size and arrayness, choice of names for
// similar parameters, templates for CreateInfo structs, parameter naming &
// ordering (especially length/array pointer pairs), etc.


= To Be Done

  * Something about Image formats
  * Something about validation scripts
  * Something about pictures
  * Glossary lists
  * New param/enum macros

= Revision History

* May 1, 2016 - Include feedback from public Github issues 120 and 190. Use
  consistent conventions for defining structures. Use American rather than
  British spelling conventions.
* March 12, 2016 - Recommend against "the value of".
* February 26, 2016 - Replace use of the "maynot{cl}" macro with "may{cl} not".
* February 16, 2016 - Place asciidoc conversion post-release.
* February 9, 2016 - Added quotation mark convention.
* February 1, 2016 - add the Oxford Comma section and issue resolution.
* January 26, 2016 - add bullet-list style description of command parameters.
* January 11, 2016 - add ``Numbers in Text'' section from WSI work.
* December 16, 2015 - Make ``begin / end'' preferred terms to ``start /
  finish''.
* December 15, 2015 - Make ``implementation'' preferred term instead of
  ``system''.
* December 13, 2015 - Add tlink{cl}/tname{cl} macros for function pointer
  types.
* December 10, 2015 - Initial release for feedback.