Documentation of the standard library

[beurdouche]

Some functions from the F* lib are not trivial to understand.
For some people that have less experience with the F* syntax, it would be very helpful to have some documentation about the interfaces exposed by the libs.

The main question though is, should we document inside or outside the code ?
This should also help with knowing what to deprecate in general #271

[catalin-hritcu]

I think this kind of documentation should be done in the code and extracted by a Javadoc-like tool. We already have an issue for creating such a tool (#88), just that nobody had time for it ... so patches welcome ;)

[markulf]

Cleaning up the F* lib is becoming somewhat urgent, and indeed we need some way of knowing what to deprecate.

[markulf]

We have a tool now, I am wondering why https://fstarlang.github.io/docs/ is linked from the F* blog but broken? Maybe its just a question of running the tool? Any output, even if very basic would be an improvement over the status quo.

[sishtiaq]

@markulf The tool seems to not have run for months. Let me check what's up.

[mtzguido]

What's the status on this? Seems the online docs are still broken, but I don't know how they're generated so as to take a look myself.

[nikswamy]

We have ongoing work on this, work being tracked in issue #1877