René's URL Explorer Experiment

Title: Auto-generate TypeScript Typings from Documentation by jvilk · Pull Request #38 · nodegit/nodegit.github.com · GitHub

Open Graph Title: Auto-generate TypeScript Typings from Documentation by jvilk · Pull Request #38 · nodegit/nodegit.github.com

X Title: Auto-generate TypeScript Typings from Documentation by jvilk · Pull Request #38 · nodegit/nodegit.github.com

Description: I am opening this PR to start a conversation. It should not be merged as-is until we determine how to integrate these typings into nodegit. Summary I have created a script that creates valid TypeScript typings for NodeGit from the documentation JSON. As NodeGit improves its documentation, the TypeScript typings will improve as well. This is what the working typings look like. Usage Run generate/index.js in the usual manner. It will generate ts/nodegit.d.ts. To create a new project that uses this file, do the following: npm install -g typescript tsd mkdir test_proj cd test_proj npm install nodegit tsd install node cp path/to/nodegit.github.com/ts/nodegit.d.ts node_modules/nodegit/lib/ Edit node_modules/nodegit/package.json to include a "typings": "lib/nodegit.d.ts" field. This tells the TypeScript compiler where to find typings for your package. Create tsconfig.json in test_proj: { "compilerOptions": { "target": "es3", "module": "commonjs", "noImplicitAny": true }, "files": [ "typings/node/node.d.ts", "test.ts" ] } Create the test.ts in test_proj: import Git = require('nodegit'); var getMostRecentCommit = function(repository: Git.Repository) { return repository.getBranchCommit("master"); }; var getCommitMessage = function(commit: Git.Commit) { return commit.message(); }; Git.Repository.open("nodegit") .then(getMostRecentCommit) .then(getCommitMessage) .then(function(message) { console.log(message); }); Compile test.ts: $ tsc Then, you can fiddle with the code in an editor that supports TypeScript, such as Visual Studio Code or Atom with the atom-typescript plugin. Simply open up the test_proj folder, and the editor will use tsconfig.json to orient itself and provide autocomplete using the typings. Limitations Currently, there are a number of weird type annotations that I have to smooth over or type to the 'any' type (see the getType function). Most of them are untyped callback functions. As you improve NodeGit's documentation, we can remove some of the logic in that function. Suggestions It would be ideal if: You included generated TypeScript declaration files in nodegit's NPM module, as illustrated in the example. You added a test to your testsuite that verifies that the produced declaration file compiles properly. If it does not, it likely indicates a documentation bug! If the script breaks, ping me. In the worst case, you can ship w/o decls for a release. In the best case, you'll fall in love with TypeScript and decide to maintain it yourselves! 😄 An alternative proposal is to put the types in the DefinitelyTyped repository, where they can be maintained separately. But I'd argue that including them into the NPM module directly would be mutually beneficial -- automatic checking of your docs, and typings for TypeScript users! Thoughts?

Open Graph Description: I am opening this PR to start a conversation. It should not be merged as-is until we determine how to integrate these typings into nodegit. Summary I have created a script that creates valid TypeSc...

X Description: I am opening this PR to start a conversation. It should not be merged as-is until we determine how to integrate these typings into nodegit. Summary I have created a script that creates valid TypeSc...

Opengraph URL: https://github.com/nodegit/nodegit.github.com/pull/38

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width