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

Question about documentation generator for this lib #812

Closed
ORESoftware opened this Issue Mar 23, 2016 · 13 comments

Comments

Projects
None yet
7 participants
@ORESoftware

I saw at the bottom of your docs

Documentation

Read the docs and eat your vegetables.

Docs are automatically generated from Immutable.d.ts. Please contribute!

Also, don't miss the Wiki which contains articles on specific topics. Can't find something? Open an issue.

So do you (Facebook) use YUIDoc, Docco, JSDoc or https://github.com/documentationjs/documentation ?

Please let me know! I would love to use something similar.

@ORESoftware

This comment has been minimized.

Show comment
Hide comment
@ORESoftware

ORESoftware Mar 24, 2016

Looks like this file gives me some clues:
https://github.com/facebook/immutable-js/blob/master/gulpfile.js

but if you could give me a definitive answer that would be really nice.

Looks like this file gives me some clues:
https://github.com/facebook/immutable-js/blob/master/gulpfile.js

but if you could give me a definitive answer that would be really nice.

@leebyron

This comment has been minimized.

Show comment
Hide comment
@leebyron

leebyron Apr 16, 2016

Collaborator

It is a custom built solution. The code for which is all found in https://github.com/facebook/immutable-js/tree/master/pages

Collaborator

leebyron commented Apr 16, 2016

It is a custom built solution. The code for which is all found in https://github.com/facebook/immutable-js/tree/master/pages

@leebyron leebyron closed this Apr 16, 2016

@ffxsam

This comment has been minimized.

Show comment
Hide comment
@ffxsam

ffxsam Apr 17, 2016

I understand the convenience for auto-generated docs, but:

findKey(
  predicate: (
    value?: T,
    key?: number,
    iter?: Iterable.Keyed<number, T>
  ) => boolean,
  context?: any
): number

This is rather illegible to me, and is kind of a bummer when I'm trying to learn Immutable. I assume ? means optional? What is T? context accepts any type of object.. but what is context? What does it mean, how do we use it?

ffxsam commented Apr 17, 2016

I understand the convenience for auto-generated docs, but:

findKey(
  predicate: (
    value?: T,
    key?: number,
    iter?: Iterable.Keyed<number, T>
  ) => boolean,
  context?: any
): number

This is rather illegible to me, and is kind of a bummer when I'm trying to learn Immutable. I assume ? means optional? What is T? context accepts any type of object.. but what is context? What does it mean, how do we use it?

@leebyron

This comment has been minimized.

Show comment
Hide comment
@leebyron

leebyron Apr 17, 2016

Collaborator

Yep, the docs aren't perfect and what they could really use are example uses

Collaborator

leebyron commented Apr 17, 2016

Yep, the docs aren't perfect and what they could really use are example uses

@ffxsam

This comment has been minimized.

Show comment
Hide comment
@ffxsam

ffxsam Apr 17, 2016

What's the best way to contribute examples? (and where should they go?) It might be cool to have a "cookbook" section that has some basic common usages, like using with Redux.

ffxsam commented Apr 17, 2016

What's the best way to contribute examples? (and where should they go?) It might be cool to have a "cookbook" section that has some basic common usages, like using with Redux.

@leebyron

This comment has been minimized.

Show comment
Hide comment
@leebyron

leebyron Apr 18, 2016

Collaborator

The docs are autogenerated from the typescript definitions file in /type-definitions, the doc block above each message turns into the description. It's just commented markdown, so it should be easy to embed example use cases right there

Collaborator

leebyron commented Apr 18, 2016

The docs are autogenerated from the typescript definitions file in /type-definitions, the doc block above each message turns into the description. It's just commented markdown, so it should be easy to embed example use cases right there

@leebyron

This comment has been minimized.

Show comment
Hide comment
@leebyron

leebyron Apr 18, 2016

Collaborator

A cookbook would also be cool! Perhaps that's worth its own section on the website (all assembled in this repo in /pages)

Collaborator

leebyron commented Apr 18, 2016

A cookbook would also be cool! Perhaps that's worth its own section on the website (all assembled in this repo in /pages)

@thomastuts

This comment has been minimized.

Show comment
Hide comment
@thomastuts

thomastuts Apr 18, 2016

Contributor

Related: you can use the gulp dev task to fire up a local server that serves the docs. Check out #844 for LiveReload functionality when changing the type definitions found in /type-definitions/.

Contributor

thomastuts commented Apr 18, 2016

Related: you can use the gulp dev task to fire up a local server that serves the docs. Check out #844 for LiveReload functionality when changing the type definitions found in /type-definitions/.

@ffxsam

This comment has been minimized.

Show comment
Hide comment
@ffxsam

ffxsam Apr 21, 2016

@leebyron I've started to put something together. Please feel free to correct/optimize any of these!

https://gist.github.com/ffxsam/6c9c4fca019eac0dec045ef303affa3c

ffxsam commented Apr 21, 2016

@leebyron I've started to put something together. Please feel free to correct/optimize any of these!

https://gist.github.com/ffxsam/6c9c4fca019eac0dec045ef303affa3c

@ffxsam

This comment has been minimized.

Show comment
Hide comment
@ffxsam

ffxsam Apr 30, 2016

Hopefully I'm not being too presumptuous here, but..

Since Immutable is under the umbrella of Facebook, and the devs working on these projects are employees of (and hence paid by) FB.. is it possible someone could be tasked with writing up new documentation? Three times now I've almost given up on using Immutable because it's so frustrating to grasp the docs. I'm not alone in this sentiment:

http://stackoverflow.com/q/29589753/5228806 (see the comments)

ffxsam commented Apr 30, 2016

Hopefully I'm not being too presumptuous here, but..

Since Immutable is under the umbrella of Facebook, and the devs working on these projects are employees of (and hence paid by) FB.. is it possible someone could be tasked with writing up new documentation? Three times now I've almost given up on using Immutable because it's so frustrating to grasp the docs. I'm not alone in this sentiment:

http://stackoverflow.com/q/29589753/5228806 (see the comments)

@seethroughtrees

This comment has been minimized.

Show comment
Hide comment
@seethroughtrees

seethroughtrees Jun 16, 2016

I have been using this library in all projects over the last year, and almost every time I reach for the docs, I think the same thing. This documentation has to be a serious barrier to entry for (at least) new users.

Having complete docs with a similar structure to lodash/ramda etc... would be extremely useful.
And would encourage lots more people to use the library in their projects.

Title -> Type Definition (non-TS) -> Description -> Example

The library is innovative on its own, the docs don't need to be, IMO.

I have been using this library in all projects over the last year, and almost every time I reach for the docs, I think the same thing. This documentation has to be a serious barrier to entry for (at least) new users.

Having complete docs with a similar structure to lodash/ramda etc... would be extremely useful.
And would encourage lots more people to use the library in their projects.

Title -> Type Definition (non-TS) -> Description -> Example

The library is innovative on its own, the docs don't need to be, IMO.

@stkrzysiak

This comment has been minimized.

Show comment
Hide comment
@stkrzysiak

stkrzysiak Jun 24, 2016

I feel the original concern raised by @ffxsam wasn't addressed completely, it was focused on that confusing syntax and what it means. Honestly, I think the docs would greatly benefit from adding examples, but also from removing this kind of stuff:

sort(comparator?: (valueA: T, valueB: T) => number): Iterable<number, T>

If it stays, the first section of the docs should be an intro to this notation, why it's used, and how to use it, as requested in #298

I feel the original concern raised by @ffxsam wasn't addressed completely, it was focused on that confusing syntax and what it means. Honestly, I think the docs would greatly benefit from adding examples, but also from removing this kind of stuff:

sort(comparator?: (valueA: T, valueB: T) => number): Iterable<number, T>

If it stays, the first section of the docs should be an intro to this notation, why it's used, and how to use it, as requested in #298

@soundyogi

This comment has been minimized.

Show comment
Hide comment
@soundyogi

soundyogi Nov 12, 2016

Learning Typescript does not take that long. Type Definitions are a great way to learn any API Surface.
They made my life much better. Also there are a lot of comments in the Immutable one:
https://github.com/facebook/immutable-js/blob/master/type-definitions/Immutable.d.ts

What I agree with is that there should be more examples.

soundyogi commented Nov 12, 2016

Learning Typescript does not take that long. Type Definitions are a great way to learn any API Surface.
They made my life much better. Also there are a lot of comments in the Immutable one:
https://github.com/facebook/immutable-js/blob/master/type-definitions/Immutable.d.ts

What I agree with is that there should be more examples.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment