search

ocsigen / eliom

Multi-tier framework for programming web and mobile applications in OCaml.
http://eliom.org
Other
298 stars 52 forks source link

File_ct module is not indexed in the documentation #514

Open sagotch opened 7 years ago

sagotch commented 7 years ago

I found this module by searching in google, after I have seen it in a piece of code. This is the module I needed, but I would have no idea it existed if I did not see this code. Probably a missing link, somewhere in the doc?

http://ocsigen.org/eliom/5.0/api/server/Eliom_registration.File_ct

vasilisp commented 7 years ago

Would a link in the description of the File module help? "If you need to modify the content type, please see File_ct", or something to that effect.

We could put it in the sidebar too, but we can't put all the Eliom_registration.X there, and I don't know where to draw the line.

sagotch commented 7 years ago

A link in the description of the File module would help.

But my mistake was that I did not read the full https://ocsigen.org/eliom/6.2/api/server/Eliom_registration page, because I assumed that every sub module would be an item of the sidebar...

sagotch commented 7 years ago

I wonder if having only some items on the left sidebar can be misleading. I would probably that it should be every sub module or none of them, but I leave you decide about this.

You can close this issue unless you want to think about it.

lisael commented 5 years ago

Hi,

I'm new to the project (just came across Graffiti), and my feelings about the documentation are mitigate. On the one hand, the tutorials are great, easy to follow and give just the right level of details. On the other hand, I miss a formal, comprehensive, auto-generated doc of the whole public API. There's a lot of details that I think are buried in the long prose of module docs. When I know what I'm looking for it's annoying I have to read a long text for the nth time.

The google search widget doesn't help, because the typical first result page is cluttered with /2.0/ /1.5/ that I deem useless.

Providing a full reference of the API has a lot of virtues (aside the bare information to the user). It may encourage developers to drop a line of doc or two, when they find a poorly documented module or signature. Users are also encouraged to contribute to the documentation, when they find that something is missing. Contributing to prose documentation is hard and intimidating. Adding docstrings is what devs do all day at work. It's something they are comfortable with.