Working on documentation

Topics: General
Coordinator
Feb 17, 2014 at 9:09 PM
Currently in the process of writing some documentation for TypeScript and associated tools. Hopefully, while it still needs to get a bit more fleshed-out, it'll already be helpful for some.

https://typescript.codeplex.com/wikipage?title=TypeScript%20Documentation

If you get a chance to read through it, let me know what you think.
Feb 18, 2014 at 7:45 PM
The advanced topic on the mixins was quite instructive, thanks for the documentation.
Feb 19, 2014 at 9:17 AM
Very helpful documentation. I like the examples (what is equivalent to what) and the topics that are outside JS (static side of class, import aliases vs var).

My comments:

1 https://typescript.codeplex.com/wikipage?title=Interfaces%20in%20TypeScript&referringTitle=TypeScript%20Documentation
  • The example with dictionary is interesting:
interface Dictionary {
  [index: string]: string;
  length: number;    // error, the type of 'length' is not a subtype of the indexer
} 
But I'm missing the explanation why there is an error here (the explanation for readers) - because in JS obj["length"] and obj.length is the same in JS the type returned from string indexer must match with other properties (as obj.length is a special case of obj["length"]);

And contrasting it with a similar looking code but using numeric index:
interface StringArray {
  [index: number]: string;
  length: number;    // this is OK as numeric indexer is used
}
  • Oh, the difference between static and instance side of class was really interesting.
2 https://typescript.codeplex.com/wikipage?title=Classes%20in%20TypeScript&referringTitle=TypeScript%20Documentation
  • Understanding private - I didn't know about that! :) Very helpful!
  • Constructor functions - I like topics such as those, showing how to work with structural typing.
  • Using a class as an interface - Another interesting thing!
3 https://typescript.codeplex.com/wikipage?title=Modules%20in%20TypeScript&referringTitle=TypeScript%20Documentation
  • The examples are good. I just wish there was a way of downloading them or running them online. That'd be a big help for beginners starting with modules (as looking at working solution is always a big help).
  • Alias - nice, shows difference between var and import.
  • Optional Module Loading and Other Advanced Loading Scenarios - nice technique, may come in handy.
  • Ambient External Modules - The example with multiple ambient external modules in one d.ts file and then /// referencing it is okay and useful in node.js context. When I'm using AMD modules written in JS I tend to add one .d.ts file per JS module so that import X = require('jslib') works without /// references and the definitions are cleanly split into small modules. Something like this:
Client:
https://github.com/wiktor-k/ts-amd/blob/master/scripts/example.ts

Native JS module:
https://github.com/wiktor-k/ts-amd/blob/master/scripts/lib/pure.js

Definition file:
https://github.com/wiktor-k/ts-amd/blob/master/scripts/lib/pure.d.ts

Maybe an example of this technique would be worth adding.
  • Trade-offs for External Modules - a note about the possibility of using external build tool to concatenate output JS files (like r.js), example here: https://github.com/wiktor-k/ts-amd/
4 https://typescript.codeplex.com/wikipage?title=Functions%20in%20TypeScript&referringTitle=TypeScript%20Documentation
  • I think it's important to highlight that the pickCard function below has only two signatures and that the implementation signature is never considered:
function pickCard(x: {suit: string; card: number; }[]): number;
function pickCard(x: number): {suit: string; card: number; };
function pickCard(x): any {
  // implementation
}
Thanks for the documentation - it's really useful - advanced and yet approachable!