Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs #672

Closed
kennetpostigo opened this issue Oct 23, 2015 · 10 comments
Closed

Docs #672

kennetpostigo opened this issue Oct 23, 2015 · 10 comments

Comments

@kennetpostigo
Copy link

Hey,

Im new to working with immutable.js and Ive been going through the docs but some of it is very confusing to me, given that I haven't worked with anything like it before so things like this:

update(updater: (value: Map<K, V>) => Map<K, V>): Map<K, V>
update(key: K, updater: (value: V) => V): Map<K, V>
update(key: K, notSetValue: V, updater: (value: V) => V): Map<K, V>

literally have me wondering what I am doing with my life. Maybe try to make the docs more friendly to newcomers to the library. The Docs are beautiful to look at, but I've literally looked at snippets and couldn't really understand what the < > things mean and why there are scattered all around the docs. Possibly adding an example of the methods in use would help a lot. Have been defaulting to looking at stackoverflow to see how others implemented the methods but going though stackoverflow looking for something is very time consuming.

Please take this as constructive criticism, I'm not attacking you guys just suggesting.

@jamesbrewerdev
Copy link

The Map<K, V> syntax is says that Map accepts keys of type K and values of type V, where K and V are arbitrary data types.

I agree that this is very confusing for someone not familiar with the syntax. I like your suggestion of adding concrete examples, but I also think it would be worthwhile to add documentation explaining the syntax used.

@kennetpostigo
Copy link
Author

Agreed @BRWR

@chiedo
Copy link

chiedo commented Nov 7, 2015

I've definitely got to follow up on this. lol. I'd be willing to submit a pull request to explain the syntax but I don't know where to start.

I'm trying to read the docs to figure out how to use and this syntax is tripping me up.

What does this mean?

findEntry(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any,
notSetValue?: V
): Array<any>

How do I practically use that?

@chiedo
Copy link

chiedo commented Nov 7, 2015

Some examples on each function would be awesome, the same way underscore.js ond lodash have them.

@chiedo
Copy link

chiedo commented Nov 7, 2015

Aha, Just found examples in the tests directory.

https://github.com/facebook/immutable-js/tree/master/__tests__

If I wrote up a bunch of examples to the documentation and submitted a pull request, what's the likelihood it would get merged and my work wouldn't go to waste? :)

@KingScooty
Copy link

The documentation is still confusing :(

@patoncrispy
Copy link

Adding my 10 cents in here, too. I'm having to learn Immutable.js by trial and error simply because I feel like it's something I really need to understand and use. While there are some basic examples in the docs, it would be great if somebody could give good concrete examples to all elements. Great work though!

@ffxsam
Copy link

ffxsam commented Mar 28, 2016

Agreed, the documentation needs work. It would be great to use a syntax that any JavaScript developer can approach immediately.

@kennetpostigo
Copy link
Author

Or have a section to that explains the syntax that is used in the documentation as I think it is type script type of notation. I think examples of each utility would be great to have.

@kennetpostigo kennetpostigo reopened this Mar 28, 2016
@leebyron
Copy link
Collaborator

Please contribute documentation to this repository once you learn best examples! This project improves when the community can contribute work like this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

8 participants
@leebyron @KingScooty @chiedo @patoncrispy @jamesbrewerdev @kennetpostigo @ffxsam and others