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

Comments

Projects
None yet
7 participants
@kennetpostigo

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.

@brwr

This comment has been minimized.

Show comment
Hide comment
@brwr

brwr Oct 23, 2015

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.

brwr commented Oct 23, 2015

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

This comment has been minimized.

Show comment
Hide comment

Agreed @brwr

@chiedo

This comment has been minimized.

Show comment
Hide comment
@chiedo

chiedo 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 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

This comment has been minimized.

Show comment
Hide comment
@chiedo

chiedo Nov 7, 2015

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

chiedo commented Nov 7, 2015

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

@chiedo

This comment has been minimized.

Show comment
Hide comment
@chiedo

chiedo 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? :)

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

This comment has been minimized.

Show comment
Hide comment
@KingScooty

KingScooty Jan 29, 2016

The documentation is still confusing :(

The documentation is still confusing :(

@patoncrispy

This comment has been minimized.

Show comment
Hide comment
@patoncrispy

patoncrispy Feb 20, 2016

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!

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

This comment has been minimized.

Show comment
Hide comment
@ffxsam

ffxsam Mar 28, 2016

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

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

This comment has been minimized.

Show comment
Hide comment
@kennetpostigo

kennetpostigo Mar 28, 2016

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.

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

This comment has been minimized.

Show comment
Hide comment
@leebyron

leebyron Apr 16, 2016

Collaborator

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

Collaborator

leebyron commented Apr 16, 2016

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