Documentation about gun HOT 46 OPEN

• 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?

from gun.

• 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

from gun.

• 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.

from gun.

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

from gun.

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

from gun.

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.

from gun.

• 2. Need examples for each Gun option.

from gun.

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

from gun.

• 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!"

from gun.

• 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, []?

from gun.

• 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.

from gun.

• 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."

from gun.

• 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

from gun.

• 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.

from gun.

• 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".

from gun.

• 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.

from gun.

• 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.

from gun.

• 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.

from gun.

• 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?

from gun.

• 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.

from gun.

• 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.)

from gun.

• 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.

from gun.

• 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."

from gun.

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

from gun.

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

from gun.

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

from gun.

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

from gun.

Yupe. :)

from gun.

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.

from gun.

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

from gun.

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

from gun.

@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.

from gun.

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"}

from gun.

@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!

from gun.

@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

from gun.

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

from gun.

@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 :)

from gun.

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

from gun.

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.

from gun.

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).

from gun.

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

from gun.

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

from gun.

@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.

from gun.

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)

from gun.

• The use of "TBD" in https://gun.eco/docs/API is vague. Have those things been programmed? If so have their API's been stabilized? Or does "TBD" mean "To Be Deprecated"?

My guess would be that it would mean that they haven't been programmed yet, but I really don't think that is true. If it is true, then that idea should be conveyed in a less ambiguous way.

from gun.

@davidbludlow good point! create/auth/recall should be stable, the others removed until future notice. Please help and delete them: https://github.com/amark/gun/wiki

from gun.