typestrong / typedoc Goto Github PK

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.

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

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'

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

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?

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.

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 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

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.

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

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.

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).

dont u think that public static method should appers on other classes?

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.

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.

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

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.

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!

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...?

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!

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/

Had to happen one day so might as well be now:

• https://github.com/grunt-ts/grunt-typedoc
• https://www.npmjs.org/package/grunt-typedoc

Was a quick one thanks some functional code I took from @rogierschouten's gulp-typedoc, I'm sure it's okay 😉

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.

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.

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.

There are tuples and protected now: https://github.com/Microsoft/TypeScript/wiki/What's-new-in-TypeScript%3F

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

1. No first letter in path.
2. In narrow screen resolution (like on phone) TOC should be hidden. Maybe some css framework like bootstrap or zurb-foundation could be helpful.
3. float: right seems to be not a good idea. It is better just without it.

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.

hi

how can i build typedoc from source?

Can we check illegal or empty comments?
thank you.

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)?

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.

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.

and another using commonJS.

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

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

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?

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.

This is somewhat related to #12 and #7

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,

i.e.

TS:

JS:

Doc:

Typedoc: Version 0.1.2
TSC: Version 1.0.1.0
CMD: typedoc --out docs src/ --includeDeclarations --target ES5

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:

1. Can you provide some brief thoughts on where things stand right now and the plans moving forward, and
2. Can you give some quick thoughts/notes on what the best way to assist would be?

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!

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.

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

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?

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.

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

It seems that comment parsing is sensitive to the type of line ending.
For example, the comment parser doesn't recognize @param or @returns if I save the file with Unix line endings (LF only), but it does work when I save with Windows line endings (CRLF).

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)?

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.

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.