Hey Christian, Thanks for bringing this to list. For the documentation to be more useful than just grabbing the code and reading the JSDoc the formatting should change (as you already pointed out, +1). It should be available in a place where developers will go to when creating a widget (the widget SDK), not on yet another different URL. As Nico mentioned, the API's are the functions we really want to have that documentation for.
I think that in the long run, we'll want to move release documentation and all docs related to it to the SDK as well. That means having a separate section that shows the generated docs for each release version as well as a description of what's changed (basically the same as goes on to the Sakai project site and listS now, but archived and consolidated in one place). I think the idea of having a JSON structure available to the widget library is a good idea. Maybe we can make use of the widget library server to generate the documentation. - Bert On 20 Jul 2012, at 19:36, Christian Vuerings wrote: > Thanks for your responses. > I've put some comments inline: > > @Nico: >> Looking at [1], it doesn't look like the current output is all that useful, > > Yes, that seems very similar to what I mentioned: >>> It doesn't look very good [1] & isn't that useful atm but I just wanted to >>> get the automation process right. > > My mail wasn't really about the current output, just about the process. > > In order to improve the output we need to: >>> update to JSDoc3 [4], update the JavaScript annotations & create a new >>> template. > >> In my mind, this means not exposing the documentation of individual widgets, >> as most of those are internal methods, and focussing on exposing the >> documentation of our core API functions. > Here and below you're repeating what I said on the UI Dev call, so I > definitely agree. > The thing we decided on was to wait with that until the formatting happened. > >> Once we do that, I think it makes sense to think about how we can feed the >> documentation seamlessly into the Widget SDK, as it would be good if we >> could continue to use that as a single point of information for widget >> developers and not introduce another location where data can be found. > > That would indeed be ideal but I'm not sure yet what the best way to do this > would be. > We could perhaps expose a JSON structure that the SDK reads in, use an iframe > or directly replace the HTML file and do that on every commit. > I think each of those is possible but it's a tradeoff between time & ease of > implementation. > I created a jira ticket for this where we can continue the discussion for > this particular feature [1] > > @Alan >> For JavaDoc there is a JavaDoc diff tool that tells you what are the >> differences between API versions. I dont suppose that that can built into >> the autodoc generation? > Afaik JSDoc3 doesn't have a tool for this feature yet but I really like the > idea. > The current process puts everything in GitHub so in theory it should be > possible to create something like this. > We could also start using the @since annotation. > > I also created an umbrella Jira to track the process of the most critical > features [2] > > > - Christian > > [1] https://jira.sakaiproject.org/browse/SAKIII-6030 > [2] https://jira.sakaiproject.org/browse/SAKIII-6027 > > On Jul 20, 2012, at 3:53 AM, Nicolaas Matthijs wrote: > >> Hi Christian, >> >> Looking at [1], it doesn't look like the current output is all that useful, >> which is often the case with automatically generated documentation. I would >> suggest that we focus on what is really useful and what people (especially >> outside the project) really need. In my mind, this means not exposing the >> documentation of individual widgets, as most of those are internal methods, >> and focussing on exposing the documentation of our core API functions. >> >> Once we do that, I think it makes sense to think about how we can feed the >> documentation seamlessly into the Widget SDK, as it would be good if we >> could continue to use that as a single point of information for widget >> developers and not introduce another location where data can be found. >> >> Hope that helps, >> Nicolaas >> >> >> >> On 20 Jul 2012, at 04:58, Christian Vuerings wrote: >> >>> Hey everyone, >>> >>> One thing I've been wanting to do for a long time is to automatically >>> generate documentation for our JavaScript API. >>> This should/would happen for every change we make. >>> >>> For now I've been using the current (old) generation tool to explore this >>> idea. >>> It doesn't look very good [1] & isn't that useful atm but I just wanted to >>> get the automation process right. >>> >>> The ultimate goal is to create something visually more appealing & useful >>> like [2] or [3]. >>> We will need to update to JSDoc3 [4], update the JavaScript annotations & >>> create a new template. >>> This will normally happen just after we make the formatting changes. >>> >>> The current automatic workflow: >>> 1) Push a change to GitHub (currently the jsdoc branch of >>> christian/3akai-ux [5]) >>> 2) Trigger a POST to a Jenkins Hook [6] >>> 3) Build the maven sakai-documentation profile [7] >>> 4) Make a commit to the gh-pages branch of christianv/oae-jsdocs [8] >>> 5) Build the GitHub page [1] >>> >>> We already have documentation for this API at [9] but the main issue with >>> it, is that it's static. >>> Which means we have duplication, it'll almost always be out of date & is >>> not easy to maintain. >>> >>> Would love to hear your thoughts about this. >>> Especially about what you would like to see & how I can improve the >>> automatic workflow. >>> >>> So far I heard: >>> - support for different OAE versions (Bert) >>> - more examples within the docs (Scot) >>> >>> >>> - Christian >>> >>> [1] http://christianv.github.com/oae-jsdocs/jsdoc/ >>> [2] http://www.fullscale.co/jsdocs/c9.html >>> [3] http://xueduany.github.com/jsdoc/out/$Kit.Animation.html >>> [4] https://github.com/jsdoc3/jsdoc >>> [5] https://github.com/christianv/3akai-ux/tree/jsdoc >>> [6] https://sakai-oae.ci.cloudbees.com/github-webhook/ >>> [7] https://github.com/christianv/3akai-ux/blob/jsdoc/pom-bundle.xml#L51 >>> [8] https://github.com/christianv/oae-jsdocs >>> [9] http://oae-widgets.sakaiproject.org/sdk/api/frontend >>> _______________________________________________ >>> oae-dev mailing list >>> [email protected] >>> http://collab.sakaiproject.org/mailman/listinfo/oae-dev >> > > _______________________________________________ > oae-dev mailing list > [email protected] > http://collab.sakaiproject.org/mailman/listinfo/oae-dev
_______________________________________________ oae-dev mailing list [email protected] http://collab.sakaiproject.org/mailman/listinfo/oae-dev
