🥢 nit(Docs): Edited for clarity #109
Conversation
There was a problem hiding this comment.
Thanks for the clean-up!
(BTW, I'll retract my verbal complaint on the call the other week about the choice of the word "contiguous". I was thinking contiguity is a word best used for grids, but apparently computer scientists have been using that word for decades to refer to bytes ranges, so yeah... good call!)
| As such, this schema is specified recursively: a pointer is either a single, | ||
| continuous sequence of bytes addresses (a **region**), or it aggregates other | ||
| As such, this schema is specified recursively: a pointer is either a reference | ||
| to a cluster of contiguous bytes (a **region**), or is an aggregation of other |
There was a problem hiding this comment.
| to a cluster of contiguous bytes (a **region**), or is an aggregation of other | |
| to a range of contiguous bytes (a **region**), or is an aggregation of other |
How about "range" instead of "cluster" here? To stress that the grouping is nothing more fancy than just one byte after the next
| pointers (a **collection**). | ||
|
|
||
| ## A **region** is a single continuous range of byte addresses | ||
| ## A **region** addresses a cluster of contiguous bytes in machine state |
There was a problem hiding this comment.
| ## A **region** addresses a cluster of contiguous bytes in machine state | |
| ## A **region** addresses a range of contiguous bytes in machine state |
|
|
||
| For simple allocations (like those that fit into a single word), the | ||
| **ethdebug/format/pointer** representation is also quite simple: just a single, | ||
| optionally named, continuous chunk of bytes in the machine state. | ||
| optionally named, cluster of contiguous bytes in the machine state. |
There was a problem hiding this comment.
| optionally named, cluster of contiguous bytes in the machine state. | |
| optionally named, sequence of contiguous bytes in the machine state. |
Have a synonym I guess ;)
| @@ -45,16 +45,16 @@ optionally named, continuous chunk of bytes in the machine state. | |||
| </details> | |||
|
|
|||
| This schema defines the concept of a **region** to be the representation | |||
| of the addressing details for a particular block of continuous bytes. Different | |||
| of the addressing details for a cluster. Different | |||
There was a problem hiding this comment.
| of the addressing details for a cluster. Different | |
| of the addressing details for a bytes range. Different |
| data locations use different, location-specific schemas for regions | ||
| (since, e.g., stack regions are very different than storage regions). The | ||
| **ethdebug/format/pointer/region** schema aggregates these using the | ||
| `"location"` field as a polymorphic discriminator. | ||
|
|
||
| ## A **collection** aggregates other pointers | ||
|
|
||
| Other allocations are not so cleanly represented by a single continuous block | ||
| of bytes anywhere. In these situations, the **ethdebug/format/pointer** | ||
| Other allocations are not so cleanly represented by a single cluster of contiguous |
There was a problem hiding this comment.
"cluster" here is probably fine if you take my other suggestions, since we'll have used the more specific word "range" or "sequence" enough times that the meaning should be driven home by now, and variety of word choice is always nice to prevent things being boring.
|
Im putting together a note that covers few more things I have in mind about pointers. I will link it here and then lets take this forward. |
Nick, I was going through the docs to catch up on the pointer schema, and I want to admit that I love your writing!
This PR adds clarity to the pointer schema overview. I replaced "continuous" to convey the intended meaning (neighboring). I also removed "continuous" when describing a single region, as it goes without saying that a region, as a unit, is inherently together. Here is the before and after:
Also, I have replaced the words "block" and "chunk" (part of whole) with the "cluster" (collection of similar things) when defining a region of bytes.