typestrong / typedoc Goto Github PK
View Code? Open in Web Editor NEWDocumentation generator for TypeScript projects.
Home Page: https://typedoc.org
License: Apache License 2.0
Documentation generator for TypeScript projects.
Home Page: https://typedoc.org
License: Apache License 2.0
Hi Sebastian,
I have a class that has both a static method "hours(n: number)" and a normal public method
"hours(): number". This is proper typescript: one is called with MyClass.hours(n) and the other with myInstance.hours().
Only the static method ends up in the documentation. Dictionary with the method name as key somewhere?
Rogier
I want to pass the -noLib option to the typescript compiler for the typedoc build. I use noLib when writing TypeScript for QtScript environments (I have a modified lib.d.ts).
My current workaround is to just overwrite the lib.d.ts for the typescript node module that typedoc transiently depends on.
Hi there!
We just recently stared using TypeScript & TypeDoc and love the promise that it provides! Unfortunately, with all of the recent TypeScript changes, I understand that it is a bit difficult to keep up and make it work properly.
So two things:
We're definitely very invested in TypeScript and would love to have the level of documentation that TypeDoc will provide! We're developers and can definitely devote a bit of time if you can help guide us down the right path?
Thanks!
When referencing a generic type with a specific type instantiation, the documentation only shows the name of the generic type and not the specific types.
note: "A of B" means A leftBracket B rightBracket (formatting fail, sorry)
example:
interface ITest of T {
field: T;
}
interface IFoo {
specificTest: ITest of string;
}
For IFoo.specificTest, I would expect to see in the documentation that the type of specificTest is ITest for T: string. Currently, all that is shown is that specificTest is an ITest.
Also, the generated documentation for ITest only indicates that ITest is generic in the type of field ("field: T in ITest of T"). It should show the generic type arguments at the top of the page for the interface.
I use TypeScript to compile modules (like for npm), and not every file used in the projects is usable for consumers of said module; many are just internals that don't have to be in the documentation.
So maybe it is good to allow TypeDoc to start resolving from a single 'main' file and only export docs for files/types that end up being visible from the main modules.
As additional complication some of the visible code might have types that come from type declaration files, so there is an odd mix of import
and <reference>
.
I'm not quite sure how this would work in practice but I'd though to add it here and see if it is interesting.
It would be nice if the use of type aliases were linked to the definition of said alias.
e.g:
export type Callback = <T>(val: T, index: number, arr: Array<T>): any;
public someFunction<T>(arr: Array<T>, callback: Callback): any {
...
}
The resulting documentation will specify the callback as type 'Callback', but not create a hyperlink to quickly view the type declaration.
Currently, it looks like Typedoc can only locate other classes (to link from a given class) if the other class is defined using a full path? E.g.:
Say I have a class in module myApp.common.controllers
named MyController
, and it has a method with a return type for myApp.common.core.SomeBaseClass
. It looks like Typedoc will only pick up the external type link for the interface if the type is declared as myApp.common.core.SomeBaseClass
. However, TSC is smart enough to compile correctly if the type is declared as just core.SomeBaseClass
, since both classes are in the same parent module myApp.common
.
I'm not sure how Typedoc actually does things (does it actually use the compiler? Or is it simply parsing the text of the files?). Either way, it would be nice if Typedoc could handle this. Obviously, the "abbreviated" paths are much shorter, as well as being more flexible (the parent modules could be changed without needing to update all the module paths).
Most likely this isn't a high priority item, but as I said, it would be nice if Typedoc could handle this.
Have you ever thought about using typedoc to generate documentation from type definitions?
I collaborate on DefinitelyTyped organisation and since we're sitting on this huge wealth of information we have this vague idea to generate documentation from all the type definitions.
I tried it with the typedoc commandline tool but it didn't work out-of-the-box.
If you'd feel like pursuing this we could put the output on http://definitelytyped.org website: we have automated builds and stuff and are looking at some webhooks so it could be very cool.
Running tsd twice fails because the out dir already exists.
Command line:
"--module", "commonjs", "--out", "./doc", "--name", MODULE_NAME, "--target", "es5"
Error:
Error: EPERM, operation not permitted 'c:\Source\node-example\example-main\doc'
at Object.fs.mkdirSync (fs.js:642:18)
at Object.sync (c:\Source\node-example\node_modules\gulp-typedoc\node_modules\typedoc\node_modules\fs.extra\node_modules\mkdirp\index.js:55:12)
at Renderer.render (c:\Source\node-example\node_modules\gulp-typedoc\node_modules\typedoc\bin\typedoc.js:4045:28)
at Application.runFromCLI (c:\Source\node-example\node_modules\gulp-typedoc\node_modules\typedoc\bin\typedoc.js:1657:31)
at Object. (c:\Source\node-example\node_modules\gulp-typedoc\node_modules\typedoc\bin\tsd:5:5)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Function.Module.runMain (module.js:497:10)
at startup (node.js:119:16)
at node.js:906:3
I've managed to make typedoc work for me and it is awesome. I've found some minor defects
float: right
seems to be not a good idea. It is better just without it.it should be given the possibility to create a custom theme starting not only by default, but from the minimal template. Or is there an easy way to achieve it anyway?
After generating all of the docs, it seems that the absolute path to the typings file is dumped onto the webpage. This is really odd, since my username is shown on the docs...?
dont u think that public static method should appers on other classes?
Had to happen one day so might as well be now:
Was a quick one thanks some functional code I took from @rogierschouten's gulp-typedoc, I'm sure it's okay 😉
I just created a typedoc plugin for the Gulp build system, maybe you'd like to refer to it in README.md. Good work creating typedoc, I was nearly going to write such a tool myself but you beat me to it :) yours looks already very good.
Let's assume we have the following "fat arrow" function:
/**
* This is a simple fat arrow function.
* @param param1 The first parameter needed by this function.
* @param param2 The second parameter needed by this function.
*/
public myFunction = (param1: string, param2: number): void => {
// do something here...
}
For this example, typedoc will display the description of param1 before the "Parameters" heading in the output, instead of below the param1 heading. The description for param2 is in the correct location (below the param2 heading).
If I change the above example by simply adding an empty @param declaration as shown below, then all parameter descriptions appear in the expected locations in the output.
/**
* This is a simple fat arrow function.
* @param
* @param param1 The first parameter needed by this function.
* @param param2 The second parameter needed by this function.
*/
public myFunction = (param1: string, param2: number): void => {
// do something here...
}
When rendering documentation with typedoc v0.1.0 on our project, I see in our ./doc directory that most file names start with a "path", e.g. _c__source_<projectname>_lib_
, essentially setting the absolute path in the file name. This also happens in the breadcrumbs, index items and "Defined in" statements. This did not happen until version 0.0.7. It would be nice to have the relative path in these places again.
For the record: I am using the following options:
--out "./doc" --name "project_name" --module commonjs --target es5 --excludeExternals
Are there any plans to add support for TypeDoc directly from within VisualStudio so that the documentation parameters can be shared with the current project (root, typescript configuration...)
If not, how would one go about configuring VS to automatically launch TypeDoc and supply project parameters to it? Post-build, custom tool?
example:
code:
function ajax<R>(pUrl: string): Promise<R> {
....
}
generated doc:
ajax<R>(pUrl: string): Promise => no reference of the generic parameter in response
code:
class Test<Data>
{
testFunction(array: Array<Data>): Array<Data> {
...
}
}
generated doc:
Class Test<Data> => ok it's good
testFunction(array: Array): Array => no reference of the Data generic parameter
There are tuples and protected now: https://github.com/Microsoft/TypeScript/wiki/What's-new-in-TypeScript%3F
functions and other entities (interfaces, classes, variables). Yes, there is no private classes and functions in typescript. But it could be specified in comments with @private
tag. It is widespread case for type definition of some javascript code to hint preferred way to use it.
In example above @private
tag was specified and displayed in function description but it has no effect on filtering.
When screen is too narrow table of contents renders at the beginning of the document and user have to scroll all the way up (it is possible to press back, but explicit button in navbar would be nice).
I've tried to customize generated files and have found it very nontrivial. It will be very nice have some example/tutorial/howtos about adding stuff into templates.
Some simple like adding ribbon for a start.
Will this project eventually support documentation generation for RequireJS projects?
Currently this appears to be getting extremely confused at resolving modules when using the --module amd flag.
I've knocked up a quick example using requireJS.
I would have expected the output to have been the same between the two projects.
I can upload the source of both if required.
Regards,
Ian Munro
Is there any way to specify a top level URL to the source files/line numbers that are output in the generated docs for functions/attributes? I'd love to make that linkable so I could say search for a function, click the source link and have it take me to that file on github where I could also see the implementation.
For example,
declare class Foo {
public y: {
/**
* foo
* @returns The current y value.
*/
(): number;
/**
* bar
* @param value The desired y value.
* @returns The calling Foo.
*/
(value: number): Foo;
}
/**
* baz
* @returns The current z value.
*/
public z(): number;
/**
* ack
* @param value The desired z value.
* @returns The calling Foo.
*/
public z(value: number): Foo;
}
Will produce this:
Notice that z
's documentation is messed up. Only the first docstring is taken.
Really, y
and z
should have identical documentation.
How much work would be required to add the source-code as optional output in the module? It would make the generated HTML a lot more beneficial for what we're doing in house...
If it's not too much work, I might try my hand at adding that support,
Hi Sebastian,
Thank you for this excellent tool! It is just what I was looking for :)
I have a suggestion for the name of the commandline binary though, as 'tsd' conflicts with https://github.com/DefinitelyTyped/tsd, a tool which many Typescript developers will likely have installed already (as I did).
Maybe rename it to the package's name (typedoc)?
Can we check illegal or empty comments?
thank you.
Hi Sebastian,
Semver and NPM treat 0.x.y versions differently from >0 versions. I did not know this and ran into typedoc not installing the latest version when I had specified "^0.0.4" in my package.json. I'll probably not be the only one. For easier updating, it would be handy to move to version 1.0.0 sometime when you're ready.
Rogier
Hi,
Rest Parameters seem to be unsupported. They show up as a single param in the docs, which is very misleading. Any plans on adding a support for it?
Kudos for a great tool!
Hi Sebastian,
You really filled a void with this tool, thank you! I'm currently deriving a class from EventEmitter, and I was searching for a way to document the events being emitted. Would it be an idea to introduce an extra @event tag? I'd be happy to try and implement this if you could give me some pointers as to how to do so.
Rogier
When I run the commandline tool on Linux, I get:
martin@laptop:~/src/typedoctest$ typedoc --out doc/ --module commonjs test.ts
: No such file or directory
martin@laptop:~/src/typedoctest$
The error message is not so helpful, but it seems this is caused by the script having Windows line endings, which confuses the Linux shell that tries to parse the "#!/usr/bin/env node" line.
See also e.g. npm/npm#4607 who struggled with the same problem. Don't know what the best solution would be in this case, as you probably have the file checked out on Windows with automatic LF <-> CRLF translation?
The file isn't auto-generated, is it? In that case, it might help marking it as binary for git, and 'manually' convert the line-endings to LF (just on that file).
I converted it in my ~/npm/bin folder for testing, and that indeed seems to work.
unfortunately typedoc does not run with typescript 1.1.0, which was relaesed a few days ago. Currently you only get the following message:
Could not find ´typescript.js´. Please install typescript, e.g. 'npm install typescript'
hi
how can i build typedoc from source?
I love typedoc, atm it's missing one thing (I guess). My project is completely based on external modules (amd in my case). I keep a comment at the top of every module file to document what the purpose of the module is. These comments don't show up in the generated documentation.
Do I understand the documentation correctly that these comments only work for internal modules? Do you consider adding support for external modules?
Splitting this issue off from this issue:
#7
Assuming that support for declarations is implemented in the above issue, a very useful companion feature would be to support for specifying some files as "third party code" (note: NOT just classifying all declaration files as third party code, but rather explicitly specifying a particular list of files or file patterns as third party code - because we might have third party code in non-declaration files and first-party code in declaration files). Then, at the top bar of the generated output page, add a new "filter" to show or hide third party code documentation.
I use external-module pattern: in the typedoc output they are listed in the 'globals' section of the menu (by their path), but the list is unsorted so it is hard to navigate.
I was trying some of your new features so I rebuild from master and installed that globally.
But I get a weird error, note how I work on D:
partition while my global npm stuff is on C:
D:\_Editing\github\tsd\DefinitelyTyped>typedoc --out docs --module commonjs --target es5 --exclude *.-tes*.ts --includeDeclarations --verbose joi
Running TypeScript compiler
Processing C:/Users/Bart/AppData/Roaming/npm/node_modules/typedoc/node_modules/typescript/bin/lib.d.ts
Skipping declaration file C:/Users/Bart/AppData/Roaming/npm/node_modules/typedoc/node_modules/typescript/bin/lib.d.ts
Processing d:/_Editing/github/tsd/DefinitelyTyped/joi/joi.d.ts
Processing d:/_Editing/github/tsd/DefinitelyTyped/node/node.d.ts
Processing d:/_Editing/github/tsd/DefinitelyTyped/joi/joi-tests.ts
Resolving project
Starting renderer
fs.js:773
return binding.link(pathModule._makeLong(srcpath),
^
Error: EXDEV, cross-device link not permitted 'c:\Users\Bart\AppData\Roaming\npm\node_modules\typedoc\bin\themes\default\assets\css\main.css'
at Error (native)
at Object.fs.linkSync (fs.js:773:18)
at Function.AssetsPlugin.copyRecursiveSync (C:\Users\Bart\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:5231:28)
at C:\Users\Bart\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:5227:38
at Array.forEach (native)
...
I see this link: https://stackoverflow.com/questions/13786160/copy-folder-recursively-in-node-js/22185855#22185855 but maybe one of fs-extra
or fs.extra
has a better recursive sync copy. Not quite sure why you'd want to 'link' really.
C:\Sources\Prototypes\business-rules-engine>typedoc --out docs/ src/validation/Validation.ts --target ES5 --module commonjs
C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:3750
childState.reflection.name = state.reflection.
^
TypeError: Cannot set property 'name' of null
at C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:3750:60
at Array.forEach (native)
at ObjectLiteralHandler.onEndDeclaration (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:3743:49)
at Dispatcher.EventDispatcher.dispatch (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:907:34)
at Dispatcher.processState (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1978:22)
at SignatureHandler.onBeginDeclaration (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:4315:45)
at Dispatcher.EventDispatcher.dispatch (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:907:34)
at Dispatcher.processState (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1964:22)
at C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1975:27
at Array.forEach (native)
at Dispatcher.processState (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1974:26)
at C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1975:27
at Array.forEach (native)
at Dispatcher.processState (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1974:26)
at C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:2898:46
at Array.forEach (native)
at ExportHandler.onBeginDeclaration (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:2892:38)
at Dispatcher.EventDispatcher.dispatch (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:907:34)
at Dispatcher.processState (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1964:22)
at C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1932:31
at Array.forEach (native)
at C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1931:30
at Array.forEach (native)
at Dispatcher.compile (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1921:38)
at Dispatcher.createProject (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1901:22)
at Application.generate (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1093:43)
at Application.runFromCommandline (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc.js:1061:22)
at Object. (C:\Users\rsamec\AppData\Roaming\npm\node_modules\typedoc\bin\typedoc:5:5)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Function.Module.runMain (module.js:497:10)
at startup (node.js:119:16)
at node.js:906:3
Right now, classes which implement interfaces don't appear to include this information. Also, interfaces don't appear to list the classes that implement the interface.
Is there a way to add some jsdoc to a typescript module declaration and have it show up in the generated docs? Our project code is broken up into a bunch of modules and it'd be nice if it was possible to have a description of what the module is for in the generated API docs.
Nice work though!
My project is build using external-module pattern and uses a lot of single-exports, but they don't show up in the generated output when I activate "Only exported".
class Foo {
// ...
}
export = Foo;
When I disable "Only exported" I see them as expected.
When I try to run typeof on OSX I get the following error:
Error: The output directory "/Users/peter/Development/cats/api_doc" exists but does not seem to be a documentation generated by TypeDoc.
Make sure this is the right target directory, delete the folder and rerun TypeDoc.
Documentation generated at /Users/peter/Development/cats/api_doc
The directory stays empty and I tried removing the directory before running typed, but made no difference. I used the following command:
./node_modules/.bin/typedoc --target es5 --out api_doc/ src/
When I run typedoc from the v0.2 branch, the links and the filenames are prepended with seemingly the absolute path to the relevant html file
Maybe it is not common case but I'd like to have ability of switching from documentation to source. Like this project do http://www.xperiments.io/TSDoc/docs/index.html
Hi I have an issue,
I have a method with inputParameters like follows: (originalValues: MyRecord, newRecord: any, fieldNames: string[], fields: string[])
and in the documentation the parameters get reordered to
(originalValues: MyRecord, fieldNames: Array, fields: Array, newRecord: any)
Why does the newRecord parameter appear last? Is it because it is of type any? Cause at the moment it has to be. And I want it to be the second parameter. How can I fix that?
According to npm list -g I have TypeDoc 0.1.2.
I hope you can help me, Thank you in advance.
Are there any plans to also expose an API and not only a command line (would love to integrate it more tightly into my IDE)?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.