@@ -135,42 +135,91 @@ Any Hoon expression, `q`, may be used to define the arm computation.
136### `+*` "lustar"
136### `+*` "lustar"
138−
138+Defines aliases within doors.
139−Produce a type constructor arm.
141##### Syntax
140##### Syntax
143−Regular: **2-fixed**.
142+Regular: **variadic**.
146−+* p=term [q=term] r=spec
145++* a=term b=hoon
149−`p` is the arm name, `q` is the name of the argument for the constructor function enclosed in square brackets, and `r` is a structure expression that defines the constructor function.
151+`a`, `c`, `e` are arm names and `b`, `d`, `f` are any Hoon expression. Note that unlike all other
152+runes with a variable number of arguments, the list of arguments of `+*` does
153+not end with a terminator.
155+`+*` arms must always come at the beginning of the battery, before any other
151##### Discussion
158##### Discussion
153−Arms produced by `+*` are essentially type constructors. They are used to construct new types from ones you already have. Consider `list`, which takes some type -- e.g., `@`, `tape`, etc. -- and returns a new type, e.g., `(list @)`, `(list tape)`, etc.
160+The primary use of `+*` is to create aliases within doors (see Examples below).
161+Aliases given by `+*` do not count towards the number of arms in the door and
162+thus are also called "virtual arms", which
163+can be important for things like Gall app cores that require a fixed number of arms.
165+Under the hood, `+*` gets compiled as `=*`'s. `+* foo bar` rewrites each `++`
166+arm beneath it in the core to include
167+`=* foo bar`. For example, the interpreter sees the Nock compiled from this Hoon expression
155−The Hoon subexpression, `r`, must be a structure expression. That is, it must be either a basic structure expression (`*`, `~`, `^`, `?`, and `@`), or a complex expression made with the `$` family of runes (including irregular variants).
169+```hoon
176+as being identical the Nock compiled from this one:
157##### Examples
189##### Examples
191+To assign an alias to a door, we often write the following.
160−> =c |%
196+This is the idomatic way to assign the alias `this` to the door.
161− +* triple [a] [a a a]
162− +* wrap-flag [a] [? a]
165−> `(triple.c @)`[12 14 16]
198+Sometimes cores, such as Gall app cores, have a fixed number of arms, but you'd
166−[12 14 16]
199+like to include more. This is where aliases employed as "virtual arms" may be of
200+use. We note that it is often better style to compose cores with `=>` or `=<` to add more arms to a
201+Gall app core. This usage of `+*` is controversial and should be minimized.
168−> `(triple.c ?)`[12 14 16]
203+```hoon
169−nest-fail
204+|_ =bowl:gall
209+This assigns the door the alias `this`, the sample of the door `samp`, and the
210+context of the door `cont`.
171−> `(triple.c ?)`[& | |]
212+You may also call functions with `+*` by making use of e.g. the `%~` rune.
174−> `(wrap-flag.c @)`[& 22]
214+```hoon