Gun: 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

[plentylife]

In the docs, regarding the constructor it states:

the previous options are actually aggregated into an object, which you can pass in yourself.
options.peers is an object, where the URLs are properties, and the value is an empty object.

That is not actually true. The object must NOT be empty, it must be in the format of {url: "_your_url_"}

[amark]

@plentylife yeah some meta-data got added to the peer objects since then, they look more like this:

{
  peers: {
    'http://localhost:8080/gun': {
      url: 'http://localhost:8080/gun',
      wire: __rawSocket
    }
  }
}

Now note, you do not have to pass it like that it just upgrades internally into an object that is represented like that.

If you see anything that is wrong in the docs, https://github.com/amark/gun/wiki/API is a wiki that can be edited, so feel free to improve it for everybody!

[plentylife]

@amark I couldn't get it to work, unless I passed it with a url property filled in.

[feat7]

@amark The docs say we can use Gun(['http://server1.com/gun', 'http://server2.com/gun'])
But this doesn't give any idea how to set up those servers for gun. A little more explanation is necessary.
Also, if not sure if we can use server.com/gun1, server1.com/gun2

[thoka]

wouldnt it be better to have monothematic issues on documentation, marked with a label "documentation" ?

[amark]

@feat7 server1.com/gun was suppose to be an example URL, not a real/actual URL. Fair point though, when we launch AXE hopefully we can update this with real URLs that anybody can use. https://gun.eco/docs/Installation#node should have some more info on how to setup - do those docs (and related pages) help at all, or need changes?

@thoka monothematic? I'm not sure what you mean, but sure! I think you have contributor access/rights? If not, I can give them to you, to help change whatever needs to be changed to make things better :)

[thoka]

@amark monothematic: one issue <=> one topic
contributor rights: not yet

[AlexYegupov]

Seems like constructor params at the gunjs-notes-app/server.js example
Gun({ file: 'db/data.json', web: server });
differs from the described at the docs
https://github.com/amark/gun/wiki/API#options

Neither 'file' parameter nor 'web' one.. Seems confusing especially for the basic example.

[mitra42]

I've found many similar discrepancies - and asked @amark about them a couple of days ago before he went on vacation. If I understood correctly he suggested adding discrepancies to the Wiki and he'd edit/correct them later.

The most common I've found are additional optional arguments (such as this case).

[bugs181]

I would also gladly accept contrib rights as well to help clarify and organize documentation structure.

[Dletta]

@bugs181 Docs are all openly editable via the Wiki here in Github.

[bugs181]

@Dletta There were a couple other things I thought I could help out with. Mostly cleaning up Git issues. I see a lot of users asking questions but their Markdown skills are limited. I could clean these issues up to be more readable as well.

[leocrawford]

Not sure if it is a bug or documentation fault, but back(0) returns the same result as back(1) which isn't as documented (or expected)

[leocrawford]

The semantics of map/on/once are not entirely clear. In particular it seems that a chain of gets with a single on at the end, will get updates/modification/deletions of final item in chain, but only additions to chain as a whole.
It would be good to know if there was a preferred way of looking for changes to any of the chain.