automerge / automerge/automerge.github.io
Reference->Lists code example is not in sync with comments describing the results of the operations
- Dominant language
- JavaScript
- Stars
- 12
- Forks
- 12
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 4
Description
The code example in the [Lists section of the reference docs](https://automerge.org/docs/reference/documents/lists/) is misleading. The example transformations presented do not reflect what's written in the comments.
The code vs. comment discrepancy starts in [this line](
https://github.com/automerge/automerge.github.io/blob/main/content/docs/reference/documents/lists.md?plain=1#L18-L19)
Which splices the list at idx 2 removing 2 elements:
// now doc.list is [0, 2, 4, 6.283185307179586]
doc.list.splice(2, 2, "automerge");
// now doc.list is [0, 'hello', 'automerge', 4]
It's impossible to arrive at the result list just by using splice.
Running the same sequence (truncated above) in my browser console gives me a very different list
```
>> Automerge.change(Automerge.init(), (d) => { d.list = []; d.list.push(2,3); d.list.unshift(0,1); d.list[3] = Math.PI; for (let i =0; i Array(3) [ 0, 2, "automerge" ]
```
Subsequent lines make a bunch of further modifications, which are not self-explanatory, and we end up with
```
[0,'hello','world',2,4]
```
I tried rewriting this section locally to make a PR, but I'm not quite sure how to get from-here-to-there, i.e which operations (or comments) to re-write. So instead I'm just flagging this as a exposition/clarity bug in the docs.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with content/docs/reference/documents/lists.md around lines 18-19 and read the complete Lists example, including the later transformations. Run the sequence in a browser console and compare each operation with its comment; done when the executable example and all documented intermediate and final lists agree.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- Half a day
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100