Document library with type definitions #5
Comments
|
I prefer DefinitelyTyped |
|
Hi, I really admire all the work you put into Gulp and am very grateful. Still, could you explain your reason? I guess that it's simply that it feels as "yet another thing to maintain"? If so, I'd just note that this library is stable, there were no changes in 2 years so it should be enough to write the types once and then there's no risk of major API/types changes. Even if I personally like Typescript, I wouldn't push it on larger components such as Following the gulp-util deprecation/gulp4-alpha.3 release, I am opening and fixing many gulp plugins. They often have some transitive dependencies that also need to be updated and each of them has their own repos/maintainers/code styles/tests so it's a very time-consuming task. This is good from a stability point of view, but having to additionally deal with DefintelyTyped just feels like some unneeded complications if you view types as documentation. It's "yet another thing to update" when there are already dozens of plugins to patch. Could I at least send a PR? |
|
Sure :) sorry, on my phone right now. |
|
Also, thank you for all your help. It's very appreciated. |
This commit adds type definitions for `plugin-error`. These types are adapted from the ones of `gulp-util`. The main changes are that the types are more based on the documentation instead of the implementation. It means that the `error` property used internally is not longer exposed as an option (it matches the tests). It also tries to prevent the use of the `plugin` option if it will be overriden. It also adds support for inference of additional properties from wrapped errors when the second argument is a real error. This commit also adds some tests for the types. It just runs the compiler with the `noEmit` option and checks for errors. Closes gulpjs#5
This commit adds type definitions for `plugin-error`. These types are adapted from the ones of `gulp-util`. The main changes are that the types are more based on the documentation instead of the implementation. It means that the `error` property used internally is not longer exposed as an option (it matches the tests). It also tries to prevent the use of the `plugin` option if it will be overriden. It also adds support for inference of additional properties from wrapped errors when the second argument is a real error. This commit also adds some tests for the types. It just runs the compiler with the `noEmit` option and checks for errors. Closes gulpjs#5
Hi,
It would be great if this project bundled its Typescript type definitions to document its API.
I am bringing this up because of the recent deprecation of gulp-util. This library is one of the recommended replacements and there are no types at the moment. By providing types directly, I hope to prevent duplicated effort in other codebases.
It would be be an improvement in documentation and distribution by packaging the types next to the Javascript implementation.
Let's start with the most obvious: it reduces friction when using this library in a Typescript project. It allows to have a single dependency on the library and get the right version of the code and types (without any mismatch issue).
Keeping type definitions as close to the source as possible makes it easier to ensure that they are up to date. Even if they are only updated by external contributors, the library's repo is a natural place to at when they want to send improvements.
Type definitions offer a more formal syntax to document the API. It nicely complement any manually-written documentation that may have some ambiguities. This allows to quickly pick new code by describing expectations and guarantees offered by the API.
Publishing type definitions in the same package as the code is the recommend method. DefinitelyTyped is more of a fallback solution when there is nowhere else to put the definitions. Despite its bots, working with this huge repo is a pain because everything is tossed together. It also has some other more fundamental flaws such as not supporting namespaced packages or individual issues.
Editors start to pull documentation for Javascript libraries from their type definitions
Some other important Javascript libraries are already documenting their own API with Typescript. These projects treat their hand-written type definitions as documentation that both humans and computers can understand. Here are some examples:
The text was updated successfully, but these errors were encountered: