search

haskell / lsp

Haskell library for the Microsoft Language Server Protocol
364 stars 90 forks source link

How to improve the documentation of lsp-types #419

Open BinderDavid opened 2 years ago

BinderDavid commented 2 years ago

As a user of the lsp library I often have to peruse the documentation of the types defined in the lsp-types library. The current documentation at https://hackage.haskell.org/package/lsp-types-1.4.0.1/docs/Language-LSP-Types.html is quite difficult to digest, since the haddocks contain almost every type that the library exports. For example, I cannot even open the documentation page on my (quite old) tablet without crashing the browser tab.

Since I often use the library, I would volunteer some of my time to improve the documentation of the lsp-types library. But before starting with this I would like to have clarification on the best direction of travel:

Could the modules in https://github.com/haskell/lsp/blob/master/lsp-types/src/Language/LSP/Types.hs be exposed modules, with the Language.LSP.Types module just reexporting the other modules? This would make it much simpler to browse the haddocks, and to document each module individually. The current separation into different modules is already quite logical, since it mostly maps one LSP request to one module.

As an alternative solution, only those modules clearly corresponding to a single LSP requests could be exposed. This would makes it possible to reorganize the remaining modules in the future without having breaking changes.

michaelpj commented 2 years ago

Could the modules in https://github.com/haskell/lsp/blob/master/lsp-types/src/Language/LSP/Types.hs be exposed modules, with the Language.LSP.Types module just reexporting the other modules?

I think that's probably fine at this point. The organization of those modules is somewhat arbitrary, so it was nice to not expose them and not have to worry about keeping them stable and sensible, but I think the rate of change isn't so high now, so it's probably safe enough!

Ideally we would just follow the organization of the spec, but it's pretty terribly organized too :sweat_smile:

michaelpj commented 1 year ago

This problem is only getting worse. Sadly, I don't know of an obvious way to fix it :/

Moreover, it's tricky because moving to generate everything from the metamodel (https://github.com/haskell/lsp/pull/458) pushes us to define everything in one module. At that point it would be a lot of manual re-exporting to put a pretty face on it. Not sure what to do.