Proposal: Typescript & Code documentation

Topics: General
May 7, 2014 at 10:32 AM
Hello,

I am currently running into one issue after the other regarding the generation of API documentation with typescript and jsdoc3. My approach is to have jsdoc parse the compiled javascript code that is generated from my typescript source.

Typescript's idea seems to be all about supporting tooling to enable the developer to work better and with higher quality on Javascript projects. At least for me, a good API documentation of the code I provide to other developers is very important to enable them to work better with my code. Documentation generation is also tooling like the IDE.

Perhaps my approach using jsdoc is wrong and there are other tools available, but telling from my research there are none available. Please hint me to alternatives if I missed them.

I want to give a brief explanation of the most annoying issues I encountered so far:
  • It's not possible to put jsdoc comments on property declarations.
    Property declarations are not directly generated javascript. So I need to assign a value explicitly in the constructor and put the property documentation there.
  • It's not possible to document interfaces.
    Interfaces are only hints to the compiler and result in no generated javascript to be picked up by jsdoc. So there is also no workaround possible as I can tell so far.
  • You need to provide a hell of a lot of redundant information in the jsdoc comments
    For an example, you need to specify the @type {string}, and also provide a full qualified @member OuterNameSpace.InnerNameSpace.ClassName#propertyName tag as well as define an @constructor Namespace.Classname tag to hint jsdoc so that it can generate the correct documentation. This information is redundant in the comments, as it's already stated clearly in the code and could be extracted.
All of these issues are not solvable by jsdoc, since the needed information is not available in the resulting javascript anymore.

So this leads to my proposal:
The Typescript compiler should be extended in terms of generating the corresponding code that will lead to full-featured jsdoc comments in a compiled javascript file.

Take, for example, this code as I'd like to comment it:
/**
* My Module
* @summary some summary
*/
module MyModule {

  /**
  * Explanation of this specific interface
  */
   export interface SomeInterface {
    /**
    * Explanation of this specific property
    */
    someProperty: string;
    /**
    * This method does someting
    * @param arg1 Provides the object to work on
    * @returns The result of something happened on arg1
    */
    doSomething(arg1: someType): SomeOtherType;
   }

  /**
  * Explanation of this specific class
  */
  export class MyClass implements SomeInterface {
    public someProperty: string;

    constructor() { // do something; }

    /**
    * Some additional information for this implementation of {@Link SomeInterface.doSomething}
    */
    public doSomething(arg1: someType): SomeOtherType { // ...  }
  }
}
In an ideal world, I'd like to tell the compiler "Generate extended docs" via some parameter. This would result in some extra generated javascript (like i.e. an empty class "ISomeInterface" with full jsdoc for the properties.

It should also automatically add the correct {typeName} tags to the @params and @returns comments. It also should add the correct @member tags to the property and method documentations.

For the properties, it then should move the comment block from the declaration to the first usage of the property in the constructor or to the initial assignment.

If the developer specifies a tag that could be auto-generated by the compiler, it would simply be omitted (and the compiler would emit a hint that this information is redundant).

The ideal result would be a fully annotated and automatically extended documentation that would run through jsdoc and provide us with a full-featured API documentation, without the hazzle I currently go through.
May 8, 2014 at 12:30 AM
I've had an idea in the back of my head at trying to document typescript applications using https://github.com/angular/dgeni. It should theoretically be possible to take the AST generated by the typescript compiler, and build a plugin for dgeni that would pull out the type information and then supply the expected tags.

I think this method would be something that would be agnostic to the typescript compiler itself, and would be something that could be managed outside of the compiler. Again I haven't looked at the implementation details of what would need to be done, but that is something I might start looking at some weekend.