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.

[metasean]

• [ ] 16. "options as true aggregates into an {obj:'ect'} with" Do what? I'm not even sure what you're trying to say here.

Applies to both get and map.

[metasean]

• [ ] 17. "options.change as true makes data only have the delta difference of the change that happened, rather than the full node again and again." Isn't this the default behavior?

[metasean]

• [ ] 18. In the on examples, it would be nice to have longer comment sections and make a clear delineation of what data is being received in each round.

[metasean]

• [ ] 19. "gun.get('user/thedoctor').val() will automatically console.log, for easy debugging purposes." Does on also console.log? if not, why not? (feels like an arbitrary 'good for the goose but not the gander distinction.)

[metasean]

• [ ] 20. "Traverses into the fields on the path, which allow you to explore the nested objects, relations, and values from the perspective of the root node that was given a key." Reads like word spaghetti. "Traverses a path's fields, allowing exploration of nested objects, relations, and values starting at the key's root node.

[metasean]

• [ ] 21. "Gives us just the phone number and whenever it changes." sounds like it gives the phone number and then a timestamp, and only a timestamp, when it is modified. Should be something like, "Responds with the current phone number and updates when the phone number is modified."

[metasean]

• [ ] 22. For map examples, the examples need some type of title, or other preparatory text, e.g. map without on or val.

[rootsical]

would be good to know if the functions return anything, if at all.. thanks

[amark]

All API methods should return a gun reference context that you can chain off of. Or were you talking about other functions?

[rootsical]

thanks. will ask a follow up question on gitter if that's ok..

[amark]

Yupe. :)

[amark]

Docs have now been rewritten like... 2 or 3 times since July 2015? Definitely all could be improved, but I'm gonna say it is safe to close this issue. If there are still problems:

Please feel free to contribute and improve the docs (they are a wiki)! Or asking questions on Stackoverflow tagged "gun" is great. And help on gitter.

gun.js.org website needs updated docs though. Will probably add some JS there that auto-pulls from github's wiki API so it is always recent. But that is a separate thing, so I'm gonna close this one, now finally! But PLEASE do complain/help/contribute to doc clarity.

[amark]

Looks like this was being used to cover ALL core documentation clarity. Woops! So I'm gonna keep it open for future use instead.

[KhaledElAnsari]

there's no content for gun.chain, I don't know if it's missing or removed

[amark]

@KhaledElAnsari good observation!

I'll add that to the TODO list of things to address in the documentation.

It still exists, but end-user-developers don't really need to use it, but it should still be documented! If you have any specific question about it right now I can try to answer it.

[KhaledElAnsari]

I'm still reading about Gun, hopefully I can use it in my next project. good job by the way