documentation

documentation copied to clipboard

We've been using documentation.js for https://github.com/keybase/keybase-bot for a while and up until our migration to TypeScript it worked perfectly. I'm currently trying to get it running once again and I'm struggling to get it to properly parse TS.

 ✘ piotr@workstation  ~/gopath/src/github.com/keybase/keybase-bot   pzduniak/ts-docs ✚  yarn docs      
yarn run v1.15.2
$ documentation readme src/index.ts --config documentation.yml --section=API
Error: Parsing file /home/piotr/gopath/src/github.com/keybase/keybase-bot/src/index.ts: Unexpected token (15:9)
    at Deps.parseDeps (/home/piotr/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/index.js:515:28)
    at fromSource (/home/piotr/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/index.js:450:44)
    at /home/piotr/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/index.js:444:17
    at ConcatStream.<anonymous> (/home/piotr/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/node_modules/concat-stream/index.js:36:43)
    at ConcatStream.emit (events.js:194:15)
    at finishMaybe (/home/piotr/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/node_modules/concat-stream/node_modules/readable-stream/lib/_stream_writable.js:475:14)
    at endWritable (/home/piotr/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/node_modules/concat-stream/node_modules/readable-stream/lib/_stream_writable.js:485:3)
    at ConcatStream.Writable.end (/home/piotr/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/node_modules/concat-stream/node_modules/readable-stream/lib/_stream_writable.js:455:41)
    at DuplexWrapper.onend (/home/piotr/gopath/src/github.com/keybase/keybase-bot/node_modules/readable-stream/lib/_stream_readable.js:577:10)
    at Object.onceWrapper (events.js:277:13)
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

The code is located there: https://github.com/keybase/keybase-bot/pull/154. The parser is failing on the following snippet of code:

import Service from './service'
import ChatClient from './chat-client'
import WalletClient from './wallet-client'
import TeamClient from './team-client'
import {BotInfo} from './utils/keybaseStatus'
import mkdirp from 'mkdirp'
import {randomTempDir, whichKeybase, rmdirRecursive} from './utils'
import {promisify} from 'util'
import {copyFile} from 'fs'
import path from 'path'
import {InitOptions} from './utils/options'

/** A Keybase bot. */
class Bot {
  public chat: ChatClient // FAILS ON THIS LINE
  public wallet: WalletClient
  public team: TeamClient
  private _workingDir: string // where KB binary copied, and homeDir (if not existing svc)
  private _service: Service

  /**
   * Create a bot. Note you can't do much too exciting with your bot after you instantiate it; you have to initialize it first.
   * @memberof Bot
   * @example
   * const bot = new Bot()
   */
  public constructor() {
    this._workingDir = randomTempDir()
    this._service = new Service(this._workingDir)
    this.chat = new ChatClient(this._workingDir)
    this.wallet = new WalletClient(this._workingDir)
    this.team = new TeamClient(this._workingDir)
  }

Any ideas on how we could make it work? Due to my unfamiliarity with this project's internals I'm struggling to figure out the root cause.

• What version of documentation.js are you using?: 11.0.1
• How are you running documentation.js (on the CLI, Node.js API, Grunt, other?): CLI using yarn

In isolation (taking this example code and closing the } to get it syntax-valid), I'm not able to replicate the issue. I'll try with the main repo.

The issue is with module dependency resolution, which is implemented by detective, a dependency via module-deps, which is lovely but woefully vintage.

To work around, you can run

documentation readme src/**/*.ts --config documentation.yml --section=API

Which just globs all the files instead of trying to resolve dependencies. Ideally we replace module-deps with something modern, long-term.

Weirdly enough I still can't get it to build :/

 ~/gopath/src/github.com/keybase/keybase-bot   pzduniak/ts-docs ●  ./node_modules/.bin/documentation readme src/**/*.ts --config documentation.yml --section=API
Error: Parsing file /Users/pzduniak/gopath/src/github.com/keybase/keybase-bot/src/index.ts: Unexpected token (15:9)
    at Deps.parseDeps (/Users/pzduniak/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/index.js:515:28)
    at fromSource (/Users/pzduniak/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/index.js:450:44)
    at /Users/pzduniak/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/index.js:444:17
    at ConcatStream.<anonymous> (/Users/pzduniak/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/node_modules/concat-stream/index.js:36:43)
    at ConcatStream.emit (events.js:194:15)
    at finishMaybe (/Users/pzduniak/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/node_modules/concat-stream/node_modules/readable-stream/lib/_stream_writable.js:475:14)
    at endWritable (/Users/pzduniak/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/node_modules/concat-stream/node_modules/readable-stream/lib/_stream_writable.js:485:3)
    at ConcatStream.Writable.end (/Users/pzduniak/gopath/src/github.com/keybase/keybase-bot/node_modules/module-deps-sortable/node_modules/concat-stream/node_modules/readable-stream/lib/_stream_writable.js:455:41)
    at DuplexWrapper.onend (/Users/pzduniak/gopath/src/github.com/keybase/keybase-bot/node_modules/readable-stream/lib/_stream_readable.js:577:10)
    at Object.onceWrapper (events.js:277:13)