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

Question about documentation generator for this lib #812

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

Question about documentation generator for this lib #812

ORESoftware opened this issue Mar 23, 2016 · 13 comments

Comments

@ORESoftware
Copy link

@ORESoftware ORESoftware commented Mar 23, 2016

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
Copy link
Author

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

@leebyron
Copy link
Collaborator

@leebyron 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
Copy link

@ffxsam 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
Copy link
Collaborator

@leebyron leebyron commented Apr 17, 2016

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

@ffxsam
Copy link

@ffxsam 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
Copy link
Collaborator

@leebyron 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
Copy link
Collaborator

@leebyron 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
Copy link
Contributor

@thomastuts 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
Copy link

@ffxsam 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
Copy link

@ffxsam 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
Copy link

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

@stkrzysiak
Copy link

@stkrzysiak stkrzysiak commented 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

@soundyogi
Copy link

@soundyogi 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
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
7 participants
You can’t perform that action at this time.