Hacker News new | past | comments | ask | show | jobs | submit login

  I have more than a sneaking suspicion that this project is essentially a proof-of-concept, and that it is not heavily used at Microsoft.
My team has been dogfooding TypeScript for several months now, providing lots of feedback and writing > 30,000 lines of code (in many cases the new TypeScript code is shorter than the original Javascript).



In this case, I must infer that the culture of documentation is not the same at Microsoft as it is at Google.

Further, how can you have a tool like this and nothing for generating type-aware documentation from your source code? Google uses jsdoc-toolkit, so this is a moot point for them. Either you guys are using this in an informal fashion, or documentation isn't that important at Microsoft, or you just haven't released the doc generation tool(s), which would be a really odd choice!


The Language Specification looks pretty extensive[1].

And TypeScript is just the language, so there's no API to document besides what your browser exposes in JS.

[1] http://www.typescriptlang.org/Content/TypeScript%20Language%...


Of course there is no API to document, and I noted the spec PDF in my top comment. Where is the manual, or something like one? At Microsoft, do they just tell a developer new to TypeScript to read the spec? Highly unlikely. MSDN is full of good documentation, and it's very weird that there's nothing of the sort for this project. I'd think that's an awful lot more important than Vim integration and such.

Even CoffeeScript had a manual very early on, and so did Dart.

I'm not saying "bad on Microsoft for releasing this!"; it's good they're starting to sort of figure out how open source works. Rather, like I said,

I think you'd be a damned fool to invest in this technology for any serious project.

Right now this is a toy.


Closure docs are pretty thin, mostly extracted symbols from code, with cryptic or misleading explanations. But a least you have clickable API listings.


I don't think this is fair at all. The Closure Library may have its dark and dusty corners, particularly for recently added/less used components, but on the whole, the library API is quite well-documented. You are mistaken about the API docs being generated from extracted code symbols; rather, it is all pulled from standard JSDoc tags. The library authors are meticulous about defining custom types rather than using ad-hoc enums and the like in their code, making the codebase itself very comfortable to reason about and making these @param and @return types very clear in their meaning.

I have my complaints about the library (certain dusty corners of goog.ui and goog.editor have hard-coded CSS classNames and Google URLs, meaning you have to use a patch queue to customize them) but I'm very pleased with the API documentation and examples. Google admittedly leans on Bolin's book (O'Reilly, 2010) too much for the community's manual-style documentation, but this is less crucial for a library than the API docs, and that book is really good :^)

The library has an extensive demo collection which is pretty nice too, and the demos generally include a minimum of 2-3 examples to show different ways to use library components (decorating vs. rendering usage of goog.ui package, for instance).

Google's real failure with Closure Tools has been marketing, but that is not my concern very much as a user. However, I see how this affects the library's adoption, so I've created a page at https://oinksoft.com/closure-tools/irc/ (I op the IRC channel) where I hope to aggregate more resources over time so that new users are able to get up-and-running without using Bolin's book.




Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact

Search: