Issue 130815.1: Template parameter refactoring

Author: Paul Robinson
Champion: Paul Robinson
Date submitted: 2013-08-15
Date revised:
Date closed:
Type: Editorial
Status: Accepted
DWARF Version: 5
Section several, pg several

Template parameter descriptions are replicated in three places
(one of them is incomplete), and missing from a fourth place.
This proposal "factors out" the template parameter descriptions
into a new section in Chapter 2, and then refers to that new
section from all the other places.

There are several other template-related issues, and while it was
tempting to include them in this rewrite, I think I've resisted
successfully. For reference the other issues are:

130402.1 (DW_AT_default_value flag to indicate a defaulted parameter)
130412.1 (non-integral non-type parameters)
130722.2 (specify template parameter entries are in source order)


New section at the end of chapter 2:

    2.x Template Parameters

    *In C++, a template is a generic definition of a class, function, member
    function, or typedef (alias).  A template has formal parameters that
    can be types or compile-time constant values; the class, function,
    member function, or typedef is instantiated differently for each
    distinct combination of type or value actual parameters.  DWARF does
    not represent the generic template definition, but does represent each
    instantiation.*

    A debugging information entry that represents a template instantiation
    will contain child entries describing the actual template parameters.
    The containing entry and each of its child entries reference a template
    parameter entry in any circumstance where the template definition
    referenced a formal template parameter.

    A template type parameter is represented by a debugging information
    entry with the tag DW_TAG_template_type_parameter.  A template value
    parameter is represented by a debugging information entry with the tag
    DW_TAG_template_value_parameter.

    A type or value parameter entry may have a DW_AT_name attribute, whose
    value is a null-terminated string containing the name of the
    corresponding formal template parameter as it appears in the source
    program.

    A type parameter entry has a DW_AT_type attribute describing the actual
    type by which the formal parameter is replaced.  A value parameter entry
    has a DW_AT_type attribute describing the type of the parameterized
    value.

    A value parameter entry has a DW_AT_const_value attribute giving the
    actual compile-time constant value as represented on the target
    architecture.


In: 3.3.7 Function Template Instantiations

In the first normative paragraph: replace "four exceptions" with "three
exceptions"; then replace items 1 and 2 with the following, and renumber
the remaining items:

    1. Template parameters are described and referenced as specified in
       Section 2.x.


In: 5.5.7 Member Function Entries

Add the following after the first paragraph, just to clarify:

    *In particular, if the member function entry is an instantiation of a
    member function template, it follows the same rules as function
    templates (see Section 3.3.7).*

In: 5.5.8 Class Template Instantiations

In the first normative paragraph replace "five exceptions" with "three
exceptions"; then replace items 1, 2 and 3 with the following, and
renumber the remaining items:

    1. Template parameters are described and referenced as specified in
       Section 2.x.


In: 5.15 Template Alias Entries

Add the following non-normative paragraph at the top, for consistency
with the non-normative text for class and function templates.

    *In C++, a template alias is a form of typedef that has template
    parameters.  DWARF does not represent the template alias definition
    but does represent instantiations of the alias.*

Replace the last sentence of the first paragraph, and the two
numbered items, with the following:

    The template alias entry has child entries describing the template
    actual parameters (see Section 2.x).


---

Accepted: 10/23/2013.  Changed from "Improvement" to "Editorial".