diff --git a/packages/web/spec/program/context/name.mdx b/packages/web/spec/program/context/name.mdx index 31fd7fb17..18295d94e 100644 --- a/packages/web/spec/program/context/name.mdx +++ b/packages/web/spec/program/context/name.mdx @@ -6,9 +6,20 @@ import SchemaViewer from "@site/src/components/SchemaViewer"; # Named contexts -Contexts may include a `name` property for distinguishing them from -other contexts. This is particularly useful inside `pick` alternatives, -where several possible contexts may apply at a given point in execution -and runtime information is needed to select which one is active. +A context may carry an optional `name`: an identifier attached to it. +Today a `name` acts as a label. Its most common use is inside a +[`pick`](/spec/program/context/pick), whose alternatives are listed +inline — a name distinguishes those alternatives from one another when +several contexts may apply at a given point in execution. + +Names are opaque strings; the format imposes no structure on them. A +name is meant to be unique within a program so it can identify a context, +but the format does **not** yet define any way to reference a context by +its name — so a declared name is currently inert, a label only. + +Naming a context is groundwork: establishing the identifier now lets a +future name-based `pick` selection reference an alternative by its name +instead of listing it inline. Compilers **should** choose names that are +meaningful to debugger users. diff --git a/schemas/program/context/name.schema.yaml b/schemas/program/context/name.schema.yaml index 759161059..bbac4c8b4 100644 --- a/schemas/program/context/name.schema.yaml +++ b/schemas/program/context/name.schema.yaml @@ -3,15 +3,23 @@ $id: "schema:ethdebug/format/program/context/name" title: ethdebug/format/program/context/name description: | - A label for distinguishing this context from other contexts. - This is particularly useful inside `pick` alternatives, - where several possible contexts may apply at a given point in - execution and runtime information is needed to select which one - is active. + An optional identifier attached to a context. - Context names are opaque strings with no format-imposed semantics. - Compilers **should** choose names that are meaningful to debugger - users. + Today a `name` acts as a label. It is most useful inside a + `pick`, whose alternatives are listed inline: a name distinguishes + those alternatives from one another when several contexts may apply + at a point in execution. + + Names are opaque strings; the format imposes no structure on them. + A name is meant to be unique within a program so it can identify a + context, but the format does **not** yet define any way to + reference a context by its name — so a declared name is currently + inert, a label only. + + It is groundwork: establishing the identifier now lets a future + name-based `pick` selection reference an alternative by its name + instead of listing it inline. Compilers **should** choose names + that are meaningful to debugger users. type: object properties: @@ -21,7 +29,7 @@ required: - name examples: - # example: naming an inlined call site - - name: "inlined-call" + # example: distinguishing a `pick` alternative + - name: "storage-layout-v2" # example: naming a generic instantiation - name: "Array"