stdlib needs docs about stdlib HOT 10 CLOSED

Couldn't get a PR ready before bed, but here's a gist @lpil .

https://gist.github.com/gamebox/2e01d96ead002b7afc1e64f9657627db

from stdlib.

You can assign this to me @lpil when you have time. I'm pretty close to complete on this task.

from stdlib.

Docs are definitely something we want, but we don't have a straightforward way of rendering any. (gleam-lang/gleam#153)

How would you intend to set up the project with documentation?

One thing we could do to start is to add documentation comments to the types and functions in the stdlib.

from stdlib.

Well they could be hosted on hexdocs, they'd just have to be manually written (not attached to the code base) until such functionality existed to do so. I'd write them the same way that erlang projects would post to hexdocs, like hackney does:
https://github.com/benoitc/hackney/tree/master/doc
https://hexdocs.pm/hackney/

Would that not work for some reason?

from stdlib.

Hackney generates their documentation using edoc, we would likely need a similar tool for Gleam. I've made some adjustments to the compiler to make generating documentation like this more possible but we still have some way to go.

from stdlib.

A good place for new contributors to start would be to add documentation comments to the functions in the stdlib. I like Elm and Elixir's documentation, they are quite clear, we could use them for guidance.

from stdlib.

I'm taking this on right now, will be submitting a proposal PR tonight with a fleshed out documentation of string - along with stubs for methods we may want to implement(cribbed from Elm's core module)

from stdlib.

Looks great!

The functions that convert to and from integers we already have in the int module.

The functions that use Char night have to wait until later- Gleam does not yet have a Char data type.

from stdlib.

We could close this, or should we expand the scope to include a plan for publishing the docs? Once gleam-lang/gleam#401 lands, we'll be able to build with --doc flag and get the docs in a /doc directory. We just need to copy those files somewhere.

from stdlib.

I think we can close this for now. We'll make a ticket for publishing docs once we're ready in the compiler. Thanks!

from stdlib.