Documentation

[metasean]

• 1. On https://github.com/amark/gun/wiki/JS-API , what is the "ect" in {obj:'ect'}?

[metasean]

• 2. Need examples for each Gun option.

[metasean]

• 3. Need comment next to each Gun example briefly explaining that code

[metasean]

• 4. "var gun = Gun({file: 'data.json'}) to change the name of the file that gets dumped to. Warning! The file module is the server's default persistence, and should only be used for local development testing only!" should be "var gun = Gun({file: 'data.json'}) to change the name of the file that gets dumped to. Warning! The file module is the server's default persistence, and should only be used for local development testing!" OR "var gun = Gun({file: 'data.json'}) to change the name of the file that gets dumped to. Warning! The file module is the server's default persistence, and should be used for local development testing only!"

[metasean]

• 5. "... on the server dumps to AWS S3, this is the preferred persistence layer." is not clear. What exactly are "server dumps"? What are the other persistence layer options? Do ' ' need to be filled in for all three object keys? Should users actually be filling in the AWS S3 key information in their JS code?

[metasean]

• 6. RE: "object is a javascript {obj:'ect'}, it can be deeply nested, be a partial, or have circular references in it, but it cannot have the following values inside of it: undefined, Infinity, NaN, []." Again, what is the "ect" in "{obj:'ect'}"? Can an object be both deeply nested and have circular references? I understand that the object keys can not be undefined, Infinity, NaN, [], but why can't the object values be undefined, Infinity, NaN, []?

[metasean]

• 7. Under the put section, the no, one, and many should be no peers, one peer, and many peers for clarity. (Yes it does become clear, but readers have additional cognitive load as they try to figure out what you are referring to, when they would be better spending their cognitive cycles on why you're telling them.

[metasean]

• 8. RE: "options is an {obj:'ect'}, no options are currently available except maybe hook specific.", specifically "...no options...except maybe..." - confusing department of confusion - a better option would be along the lines of, "options is an {keys:'values'}, currently there are no options in gun core, but specific hook implementations may have options."

[metasean]

• 9. "gun.put({hello: "world"}) blindly fire and forget." should have some caveat that there isn't a key (i.e. the "forget" part, and best practice is to have a key

[metasean]

• 10. RE: "Graph based data" ... "both objects get saved into a graph." The "both parts" section should be moved above the code sample. The "Graph based data" as a title is useful, but (a) slightly more explanation before the code, of what the reader should be focusing on, would be useful, (b) the current "both objects" section is visually lost under the code block, and (c) picking up mid-sentence after the code block is cognitively jarring

[metasean]

• 11. "options as a 'string' is a soul that you forcibly want to associate the key with, ignoring the current context that key is chained on." - "soul" hasn't been mentioned on this page before. A brief explanation and link to more info is appropriate.

[metasean]

• 12. "gun.put({hello: "world"}).key('message/from/thedoctor') blindly fire and forget." Since it has a key, it isn't being forgotten like a key-less put is; it is much more a "update the object and assign it this key, so that it can be easily referenced".

[metasean]

• 13. "Opens up a gun reference to the root object you had saved to that key. It will load the node so you can further manipulate it." - The first sentence is unnecessarily verbose. This is due, in part, to the fact that the page doesn't presume knowledge of gun nodes. I think it may be best to have a brief primer on (a) gun nodes, (b) trees in gun, (c) circular references in gun, and (d) gun souls either at the beginning of the page or, preferably, as a separate page. Then the first sentence could simple read, "Accesses the keyed gun node for further operations.." This also address the bullet above about "soul" not having been mentioned.

[metasean]

• 14. "callback is a function(){} which gets called as callback(err, graph) used for err handling and the raw graph. Note that you do not want to use this callback for every day development, as it gets called repeatedly to comply the wire protocol. Use on or val instead, they are convenience methods, this callback is for hooks and extensions." should be "callback is a function(){} which gets called as a callback(err, graph) and is used for err handling and the raw graph. Note that this callback is repeatedly called, therefore it shouldn't be used for everyday development. Instead, use on or val, as they are optimized for application use, while the gun callback is engineered primarily for hooks and extensions."

Same comments apply to get and path.

[metasean]

• 15. "options.force as true to pull from the local persistence layer or a peer rather than memory." Should briefly state the pros and cons, or at the least why a programmer should prefer one over the other. It's alluded to in an example, but users shouldn't have to read through the example to get basic info such as this.