Sample JS Docs for Share Widget Library

[ddraper]

This blog is somewhat out of date - the new framework became Aikau and the JSDoc can be found here.

Introduction

Any new framework is going to live and die by the strength of it's documentation, so it's important that we try to ensure that we make as much information on the new Alfresco Share widget library available as possible. In an ideal world we'd have have a big team working on the widgets (and the supporting framework) that would include people dedicated to writing blogs, tutorials and documentation for it.  Sadly that's not the case at the moment but we're going to do the best we can to support the Alfresco Community in getting up to speed with this new approach for Alfresco Share development

Source Documentation

From the outset we wanted to ensure that we provided useful documentation within the source through commenting and JSDoc. Hopefully we've created well-commented code that is easy to read and understand but sometimes it's better to read and navigate comments via a browser through linked files rather than in the source itself. Therefore we've added comments using a JSDoc3 supported syntax that allows us to build a HTML representations of the source documentation.

We haven't included or published this documentation with the release of Alfresco Enterprise 4.2 for a few reasons:

• We haven't had the time to put together an Alfresco specific template for the HTML output

• Many of the widgets are still of beta quality (as explained at Alfresco Summit and mentioned briefly in my last post)
• We're not completely satisfied with the current quality of the existing documentation

I also discovered whilst writing this post that there are still some syntax errors in the comments that prevents the released code from being used to generate the documentation. However, in the spirit of getting information out to the Community early I wanted to provide a sample of what to expect in future releases.

Writing Widgets Supporting JSDoc3

We encountered a few issues when initially trying to generate the JSDoc due to the AMD-style template that we were using for our source files. This means that we have had to adopt a specific use of the available tags to generate output that meets our needs.

You can browse the source files to get an idea of the tags that we've used, but if you are writing your own widgets and want to document them in a similar style then you should follow these broad guidelines:

1. Use @module, @extends, @mixes and @author in the root comment block
2. Use @instance for each function and variable
3. Use @type and @default for each variable
4. Use @param and @returns as appropriate for each function

Sample JS Doc

You can download a current snap-shot of the widget library documentation here. This was generated using the code currently on the Community SVN trunk (although I need to to fix a few tagging syntax errors that I will commit as soon as possible). Please bear in mind that this is very much a work in progress but as always we welcome your feedback. If you find any issues such as typos, missing links or specific areas where a better explanation is required then please let us know.