Use TypeScript modifiers to determine access

[SirDarquan]

Issue #168 added code to allow us to use the @Private, @Protected and @public tags in TypeScript but I think the point was missed. The promise of using TypeScript is that we shouldn't have to define some of our commenting metadata. TypeScript already provides facilities to determine the access level of a method and we should use that. With that said, here's what needs to be done in readTypeScriptModules.js:

1. We need to create a function that knows how to determine what access level the current member is. Each memberSymbol has a property that may contain its modifiers. Also, there are more modifiers than just public, private and protected, so we need to filter on the ones we're interested in.

   function getAccess(modifiers){
     if(!modifiers){
       return 'public';  //javascript default modifier is public
     }
     var _modifier = _.filter(modifiers,function(modifier){
         return [ts.SyntaxKind.PrivateKeyword, ts.SyntaxKind.ProtectedKeyword, ts.SyntaxKind.PublicKeyword].indexOf(modifier.kind) != -1;
       });
       if(!_modifier.length){
         return 'public'; //no modifiers found, so again the default is public
       }
       else{
         //TypeScript only allows one visibility modifier, so we check which one it is.
         switch(_modifier[0].kind){
           case ts.SyntaxKind.PrivateKeyword:
             return "private";
           case ts.SyntaxKind.ProtectedKeyword:
             return "protected";
           case ts.SyntaxKind.PublicKeyword:
             return "public";
         }
       }
   }

2. Next we modifiy createMemberDoc to call getAccess:

   var memberDoc = {
     docType: 'member',
     classDoc: classDoc,
     name: memberSymbol.name,
     decorators: getDecorators(memberSymbol),
     content: getContent(memberSymbol),
     fileInfo: getFileInfo(memberSymbol, basePath),
     location: getLocation(memberSymbol),
     access: getAccess(memberSymbol.declarations[0].modifiers) //This is the new line of code
   };

3. We update code that wants to know of the member is private or not. Specifically I'm talking about the hidePrivateMember check. Previously it was:

   } else if (!hidePrivateMembers || memberSymbol.name.charAt(0) !== '_') {

   but now it should be

   } else if (!hidePrivateMembers || memberDoc.access != "private") {

Changing number 3 also fixes what I believe to be a bug. If you define an index property on a class, TypeScript exposes it as __index but if you hidePrivateMembers and use '_' as your basis for determining private members, you lose the ability to inform your API consumer that there is an index on the class and that doing myObj["key"] = value is ok.

I've modified my local version with this code, so it works as-is but I can see where it may need some work. I would have made a pull request but time constraints on my current project prevents me from delving to deep with this. I hope this code makes it into the codebase in some form.

[petebacondarwin]

This sounds good to me. Anyone fancy putting a PR together?

[wingedfox]

@petebacondarwin, I suppose 'hidePrivateMembers' should be a feature of the document renderer.

As by now I build docs for a mixed-source project and I dislike the idea of using such property on each processor.

[petebacondarwin]

It's a bit more complicated than just rendering. For instance, what if someone created a {@link somePrivateMember}? If only the doc renderer ignores private members then this link would not be flagged up as invalid...

Perhaps we could have a simple processor that runs after the API docs have been read/created and removes those that are marked as private? This would have to run quite early in the pipeline to prevent other processors from picking up those docs.

[wingedfox]

Renderer should not 'ignore' private members, but follow the links as well.

It is a good idea to follow jsdoc behaviour and allow to choose which parts are accessible after rendering.