search

ebkalderon / tower-lsp

Language Server Protocol implementation written in Rust
Apache License 2.0
962 stars 54 forks source link

Add inline documentation to examples #331

Open TimJentzsch opened 2 years ago

TimJentzsch commented 2 years ago

I think it would be valuable to add some inline documentation to the example files to make it easier to get started with tower-lsp.

Especially a top level comment explaining what is being showcased in this example, as well as maybe client usage notes would be very useful.

I'd also be willing to help with this if you want to add it.

ebkalderon commented 2 years ago

Sure, that sounds like it would be a great addition! Provided that the documentation isn't too heavy to the point of distraction and focuses primarily on explaining "why" and "how" behind the API, of course. Pull requests are always welcome and appreciated in this regard!

However, now that I think about it, perhaps it might be even more valuable to improve the rustdoc output for the crate by fleshing out the prose and adding inline Rust examples there rather than annotating the crate examples. Any thoughts on this?

TimJentzsch commented 2 years ago

I think you're right on both points, not adding too much documentation is a good idea and improving the API doc itself would be valuable!