search

LightTable / Clojure

Light Table Clojure language plugin
MIT License
99 stars 47 forks source link

Clojure plugin docstrings #89

Closed carocad closed 8 years ago

carocad commented 8 years ago

Hey guys, while researching a bit about watches, I found out a lot about the way LT and especially the Clojure plugins evaluates and watches source code. As suggesteed by @kenny-evitt I documented the related functions in hope for the future ;)

Hope it helps

kenny-evitt commented 8 years ago

@carocad Cool and thanks! I'll take a longer look soonish.

kenny-evitt commented 8 years ago

@carocad I'm going to defer to @cldwalker and @rundis about whether to merge this as they've been more active in maintaining this code.

Would you mind writing up some of what you learned, or already knew, about watches – in a separate (Markdown) document too? That's what I was expecting originally.

carocad commented 8 years ago

@kenny-evitt initially I thought the same: put all of it in a separate file. Nevertheless as you suggested and, after seeing the strong relation of watches to how LT works in general I thought that it would be better to actually document the source code.

I already added the relevant links to my sources on the PR. Those blogs and Google group post explain it clear and better that I could with a simple markdown document, so I don't see a reason to put it in a separate document now.

There is only left to document the watched-range function inside LT itself. I will do that one soon ...

kenny-evitt commented 8 years ago

@carocad Sorry for not being clear – the docstrings and comments are great but an overview document would be helpful too to understand how things fit together. I'm thinking of that document like an integration test versus the docstrings and comments like unit tests. An initial version could just quote, or even copy, the blog posts and discussion thread verbatim.

sbauer322 commented 8 years ago

@carocad - I find the work done here quite useful and it is a pity this was never merged...

Would you be interested in finishing this PR or would you prefer that I take it over? There are a few relatively minor changes to make...

I'm not worried about the overview document unless you were interested in it.

carocad commented 8 years ago

@sbauer322 You can take over if you so wish to. I have made quite some PR that would definitely appreciate some love ;)

sbauer322 commented 8 years ago

@cldwalker if you were planning on taking this over, it might be beneficial to use the :doc key I am adding for issue https://github.com/LightTable/LightTable/issues/2206... it was the reason I started on that task before this one! :smile:

Since you assigned yourself to this task, do let me know if you were going to take it on.

cldwalker commented 8 years ago

@sbauer322 Good to know. I'll hold off until LightTable/LightTable#2206 is sorted out. I'm also happy to review if you want to take this on

sbauer322 commented 8 years ago

Closing as #93 has been opened with some additional changes.