search

tomfaulhaber / autodoc

The robot to automatically generate documentation for Clojure code. Used to generate the API docs for clojure.org.
121 stars 26 forks source link

CLJS Support #16

Open gtrak opened 10 years ago

gtrak commented 10 years ago

Would you welcome CLJS support?

I've got a working proof of concept in my branch, relying on a dumped compiler analysis file, the generation of which will potentially make it into cljs soon. However, it could also be used with runtime-available data.

Screenshot: http://i.imgur.com/BrAc61U.png?1

Diff: https://github.com/gtrak/autodoc-cljs/commit/0c4bcf15345c8268ac83eb247e5c94da689fd47c

It's not quite ready for a proper pull-request, but I wanted to know if I should work towards a proper integration.

Here's a related issue I filed with lein-cljsbuild, which I hacked in order to generate the dump. https://github.com/emezeske/lein-cljsbuild/issues/283

tomfaulhaber commented 10 years ago

I am completely in support of CLJS support in autodoc.

My only real concern has to do with maintainability. That is, I worry that changes on the CLJ side might break stuff on the CLJS side and vice-versa. Unfortunately, autodoc has no real tests to prevent this in a systematic way.

However, I don't think this should stand in the way of moving forward. We can think about how to add tests that aren't too brittle as we go along.

So, have at it!

On Jan 13, 2014, at 2:22 PM, Gary Trakhman notifications@github.com wrote:

Would you welcome CLJS support?

I've got a working proof of concept in my branch, relying on a dumped compiler analysis file, the generation of which will potentially make it into cljs soon. However, it could also be used with runtime-available data.

Screenshot: http://i.imgur.com/BrAc61U.png?1

Diff: gtrak@0c4bcf1

It's not quite ready for a proper pull-request, but I wanted to know if I should work towards a proper integration.

Here's a related issue I filed with lein-cljsbuild, which I hacked in order to generate the dump. emezeske/lein-cljsbuild#283

— Reply to this email directly or view it on GitHub.

venantius commented 8 years ago

It's been quite a while since this issue was opened, but it would be great to see some movement on this. In particular, the ClojureScript project itself would love to have autodoc for generating documentation for its cljs.*.api namespaces (see http://dev.clojure.org/jira/browse/CLJS-1446).

This will require support for both .cljs and .cljc files.

I'm not really sure how to go about approaching this as I ran into some unrelated issues when trying to build the current version of Autodoc, but I'll file a separate issue for that.

tomfaulhaber commented 8 years ago

I agree, but I'm not sure that @gtrak was on exactly the right track.

Here's how I would think about it:

  1. Create a autodoc-collect variant that processes cljs files (and cljc files handled as clojurescript). It should produce an identical data structure to that produced by autodoc collect.
  2. Teach autodoc to be smart about whether to call autodoc-collect, autodoc-collect-cljs, or both (the new tools.namespace should help a lot here).
  3. Merge together the output of the two programs (especially interesting for cljc files).
  4. Modify the output format to indicate language variant when two variants exist.

A slightly different approach would be to make autodoc-collect smart enough to handle both languages. This is dangerous, though, since autodoc-collect is specifically designed to handle clojure versions all the way back to v1.1 and is, therefore, pretty limited.

As I mentioned above, I am happy to have contributions in this area. One thing that would be a huge help work on the ClojureScript version of autodoc-collect. My expertise on the mechanics of ClojureScript is weak and not likely to get a lot better in the near future, so that would accelerate this issue a bunch.

venantius commented 8 years ago

I'm inclined to agree that a new approach may be needed. At the moment my familiarity with ClojureScript is still pretty weak as I only started tinkering with it a week or so ago, so I'm probably not the right person to take this on. If that changes I'll come back :P