style: use jsdocs for function descriptions

src/api/install.ts

@@ -71,12 +71,12 @@ export type StrictPublicInstallationOptions = StrictBasicOptions & {
   linkLocal: boolean
 }
 
-/*
+/**
  * Perform installation.
- *
+ * 
+ * @example
  *     install({'lodash': '1.0.0', 'foo': '^2.1.0' }, { quiet: true })
  */
-
 export default async function (fuzzyDeps: string[] | Dependencies, optsNullable: PublicInstallationOptions) {
   let packagesToInstall = mapify(fuzzyDeps)
   const installType = packagesToInstall && Object.keys(packagesToInstall).length ? 'named' : 'general'

src/binify.ts

@@ -1,16 +1,16 @@
 import {Package} from './api/initCmd'
 
-/*
+/**
  * Returns bins for a package in a standard object format. This normalizes
  * between npm's string and object formats.
  *
+ * @example
  *    binify({ name: 'rimraf', bin: 'cmd.js' })
  *    => { rimraf: 'cmd.js' }
  *
  *    binify({ name: 'rmrf', bin: { rmrf: 'cmd.js' } })
  *    => { rmrf: 'cmd.js' }
  */
-
 export default function binify (pkg: Package) {
   if (typeof pkg.bin === 'string') {
     const obj = {}

src/cmd/install.ts

@@ -1,11 +1,10 @@
 import install, {PublicInstallationOptions} from '../api/install'
 
-/*
+/**
  * Perform installation.
- *
+ * @example
  *     installCmd([ 'lodash', 'foo' ], { quiet: true })
  */
-
 export default function installCmd (input: string[], opts: PublicInstallationOptions) {
   return install(input, opts)
 }

src/fetch.ts

@@ -14,10 +14,9 @@ export type FetchOptions = {
   got: Got
 }
 
-/*
+/**
  * Fetches a tarball `tarball` and extracts it into `dir`
  */
-
 export default function fetch (dir: string, dist: PackageDist, opts: FetchOptions) {
   if (dist.location === 'remote') {
     return opts.got.getStream(dist.tarball)

src/fs/forceSymlink.ts

@@ -4,11 +4,10 @@ const debug = createDebug('pnpm:symlink')
 
 export type SymlinkType = 'junction' | 'dir'
 
-/*
+/**
  * Creates a symlink. Re-link if a symlink already exists at the supplied
  * srcPath. API compatible with [`fs#symlink`](https://nodejs.org/api/fs.html#fs_fs_symlink_srcpath_dstpath_type_callback).
  */
-
 export default async function forceSymlink (srcPath: string, dstPath: string, type: SymlinkType) {
   debug(`${srcPath} -> ${dstPath}`)
   try {

src/fs/mkdirp.ts

@@ -2,10 +2,9 @@ import mkdirp = require('mkdirp')
 import createDebug from '../debug'
 const debug = createDebug('pnpm:mkdirp')
 
-/*
+/**
  * mkdir -p as a promise.
  */
-
 export default function (path: string) {
   return new Promise((resolve, reject) => {
     debug(path)

src/fs/relSymlink.ts

@@ -6,10 +6,9 @@ import os = require('os')
 // lack permission to create them
 const symlinkType: SymlinkType = os.platform() === 'win32' ? 'junction' : 'dir'
 
-/*
+/**
  * Relative symlink
  */
-
 export default function relSymlink (src: string, dest: string) {
   // Junction points can't be relative
   const rel = symlinkType !== 'junction' ? path.relative(path.dirname(dest), src) : src

src/fs/requireJson.ts

@@ -12,10 +12,9 @@ export type RequireJsonOptions = {
 
 const cache: PackagesCache = {}
 
-/*
+/**
  * Works identically to require('/path/to/file.json'), but safer.
  */
-
 export default function requireJson (pkgJsonPath: string, opts?: RequireJsonOptions): Package {
   opts = opts || {ignoreCache: false}
   pkgJsonPath = path.resolve(pkgJsonPath)

src/fs/unsymlink.ts

@@ -1,10 +1,9 @@
 import fs = require('mz/fs')
 import {Stats} from 'fs'
 
-/*
+/**
  * Removes a symlink
  */
-
 export default function unsymlink (path: string) {
   return fs.lstat(path)
   .then((stat: Stats) => {

src/install/index.ts

@@ -63,26 +63,22 @@ export type PackageContext = {
 
 export type InstallLog = (msg: string, data?: Object) => void
 
-/*
+/**
  * Installs a package.
  *
- *     install(ctx, 'rimraf@2', './node_modules')
- *
- * Parameters:
- *
- * - `ctx` (Object) - the context.
- *   - `root` (String) - root path of the package.
- *   - `log` (Function) - logger
- *
  * What it does:
  *
  * - resolve() - resolve from registry.npmjs.org
  * - fetch() - download tarball into node_modules/.store/{name}@{version}
  * - recurse into its dependencies
  * - symlink node_modules/{name}
- * - symlink bins
+ *
+ * @param {Object} ctx - the context.
+ * @param {Object} pkgMeta - meta info about the package to install.
+ *
+ * @example
+ *     install(ctx, 'rimraf@2', './node_modules')
  */
-
 export default async function install (ctx: InstallContext, pkgMeta: PackageMeta, modules: string, options: InstallationOptions): Promise<InstalledPackage> {
   debug('installing ' + pkgMeta.rawSpec)
   if (!ctx.builds) ctx.builds = {}
@@ -193,12 +189,11 @@ export default async function install (ctx: InstallContext, pkgMeta: PackageMeta
   }
 }
 
-/*
+/**
  * Builds to `.store/lodash@4.0.0` (paths.target)
  * If an ongoing build is already working, use it. Also, if that ongoing build
  * is part of the dependency chain (ie, it's a circular dependency), use its stub
  */
-
 function buildToStoreCached (ctx: InstallContext, target: string, buildInfo: PackageContext, log: InstallLog): Promise<Package> {
   // If a package is requested for a second time (usually when many packages depend
   // on the same thing), only resolve until it's fetched (not built).
@@ -212,11 +207,10 @@ function buildToStoreCached (ctx: InstallContext, target: string, buildInfo: Pac
   )
 }
 
-/*
+/**
  * Builds to `.store/lodash@4.0.0` (paths.target)
  * Fetches from npm, recurses to dependencies, runs lifecycle scripts, etc
  */
-
 async function fetchToStore (ctx: InstallContext, target: string, dist: PackageDist, log: InstallLog) {
   // download and untar
   log('download-queued')
@@ -266,11 +260,10 @@ async function buildInStore (ctx: InstallContext, target: string, buildInfo: Pac
   })
 }
 
-/*
+/**
  * Symlink a package into its own node_modules. this way, babel-runtime@5 can
  * require('babel-runtime') within itself.
  */
-
 async function symlinkSelf (target: string, pkg: Package, depth: number) {
   debug(`symlinkSelf ${pkg.name}`)
   if (depth === 0) {
@@ -286,14 +279,14 @@ function escapeName (name: string) {
   return name && name.replace('/', '%2f')
 }
 
-/*
+/**
  * Perform the final symlinking of ./.store/x@1.0.0 -> ./x.
  *
+ * @example
  *     target = '/node_modules/.store/lodash@4.0.0'
  *     modules = './node_modules'
  *     symlinkToModules(fullname, modules)
  */
-
 async function symlinkToModules (target: string, modules: string) {
   // TODO: uncomment to make things fail
   const pkgData = requireJson(join(target, 'package.json'))
@@ -306,11 +299,10 @@ async function symlinkToModules (target: string, modules: string) {
   await relSymlink(target, out)
 }
 
-/*
+/**
  * If `path` doesn't exist, run `fn()`.
  * If it exists, don't do anything.
  */
-
 async function make (path: string, fn: Function) {
   try {
     await fs.stat(path)
@@ -320,10 +312,9 @@ async function make (path: string, fn: Function) {
   }
 }
 
-/*
+/**
  * Save promises for later
  */
-
 function memoize (locks: CachedPromises, key: string, fn: () => Promise<void>) {
   if (locks && locks[key]) return locks[key]
   locks[key] = fn()

src/install/isAvailable.ts

@@ -4,17 +4,17 @@ import fs = require('mz/fs')
 import {PackageSpec} from '../install'
 import {Package} from '../api/initCmd'
 
-/*
+/**
  * Check if a module exists (eg, `node_modules/node-pre-gyp`). This is the case when
  * it's part of bundleDependencies.
  *
  * This check is also responsible for stopping `pnpm i lodash` from doing anything when
  * 'node_modules/lodash' already exists.
  *
+ * @example
  *     spec = { name: 'lodash', spec: '^3.0.2' }
  *     isAvailable(spec, 'path/to/node_modules')
  */
-
 export default async function isAvailable (spec: PackageSpec, modules: string) {
   const name = spec && spec.name
   if (!name) return false

src/install/linkBins.ts

@@ -38,20 +38,19 @@ function isScopedPkgsDir (dirPath: string) {
   return path.basename(dirPath)[0] === '@'
 }
 
-/*
+/**
  * Links executable into `node_modules/.bin`.
  *
- * - `modules` (String) - the node_modules path
- * - `target` (String) - where the module is now; read package.json from here
- * - `fullname` (String) - fullname of the module (`rimraf@2.5.1`)
+ * @param {String} modules - the node_modules path
+ * @param {String} target - where the module is now; read package.json from here
  *
+ * @example
  *     module = 'project/node_modules'
  *     target = 'project/node_modules/.store/rimraf@2.5.1'
  *     linkPkgBins(module, target)
  *
  *     // node_modules/.bin/rimraf -> ../.store/rimraf@2.5.1/cmd.js
  */
-
 export async function linkPkgBins (modules: string, target: string) {
   const pkg = tryRequire(path.join(target, 'package.json'))
 
@@ -135,10 +134,9 @@ function cmdShim (proxyPath: string, targetPath: string) {
   ])
 }
 
-/*
+/**
  * Like `require()`, but returns `undefined` when it fails
  */
-
 function tryRequire (path: string) {
   try { return requireJson(path) } catch (e) { return null }
 }

src/install/postInstall.ts

@@ -29,11 +29,10 @@ export default async function postInstall (root_: string, log: Function) {
   }
 }
 
-/*
+/**
  * Run node-gyp when binding.gyp is available. Only do this when there's no
  * `install` script (see `npm help scripts`).
  */
-
 async function checkBindingGyp (root: string, log: Function) {
   try {
     await fs.stat(path.join(root, 'binding.gyp'))

src/installMultiple.ts

@@ -9,13 +9,13 @@ export type MultipleInstallationOptions = InstallationOptions & {
   dependent: string
 }
 
-/*
+/**
  * Install multiple modules into `modules`.
  *
+ * @example
  *     ctx = { }
  *     installMultiple(ctx, { minimatch: '^2.0.0' }, {chokidar: '^1.6.0'}, './node_modules')
  */
-
 export default function installMultiple (ctx: InstallContext, requiredPkgsMap: Dependencies, optionalPkgsMap: Dependencies, modules: string, options: MultipleInstallationOptions): Promise<InstalledPackage[]> {
   requiredPkgsMap = requiredPkgsMap || {}
   optionalPkgsMap = optionalPkgsMap || {}

src/logger/pretty.ts

@@ -5,9 +5,10 @@ observatory.settings({ prefix: '  ', width: 74 })
 
 import {PackageSpec} from '../install'
 
-/*
+/**
  * Logger.
  *
+ * @example
  *     add = logger()
  *
  *     log = add({ name: 'rimraf', rawSpec: 'rimraf@2.5.1' })
@@ -17,7 +18,6 @@ import {PackageSpec} from '../install'
  *     log('depnedencies')
  *     log('error', err)
  */
-
 export default function () {
   const tasks = {}
 

src/logger/simple.ts

@@ -14,10 +14,9 @@ const s = {
   bold: chalk.bold
 }
 
-/*
+/**
  * Simple percent logger
  */
-
 export default function () {
   const out = process.stdout
   const progress = { done: 0, total: 0 }

src/network/got.ts

@@ -67,7 +67,6 @@ export default (opts: GotOptions): Got => {
   /*
    * waits in line
    */
-
   const get: GetFunc = retrier((url: string, options?: GotOptions) => {
     const throater = getThroater()
     const key = JSON.stringify([ url, options ])
@@ -91,7 +90,6 @@ export default (opts: GotOptions): Got => {
   /*
    * like require('got').stream, but throated
    */
-
   const getStream = retrier((url: string, options?: GotOptions) => {
     const throater = getThroater()
     return new Promise((resolve, reject) => {
@@ -116,7 +114,6 @@ export default (opts: GotOptions): Got => {
   /*
    * Extends `got` options with User Agent headers and stuff
    */
-
   function extend (url: string, options: GotOptions): GotOptions {
     if (!options) options = Object.assign({}, forcedRequestOptions)
     if (url.indexOf('https://') === 0) {

src/registryFor.ts

@@ -1,9 +1,8 @@
 import registryUrl = require('registry-url')
 
-/*
+/**
  * Returns the registry needed for a certain package.
  */
-
 export default function registryFor (pkg: string) {
   if (pkg.substr(0, 1) === '@') {
     return registryUrl(pkg.split('/')[0])

src/resolve/index.ts

@@ -33,6 +33,7 @@ export type ResolveOptions = {
 /**
  * Resolves a package in the NPM registry. Done as part of `install()`.
  *
+ * @example
  *     var npa = require('npm-package-arg')
  *     resolve(npa('rimraf@2'))
  *       .then((res) => {

src/resolve/npm.ts

@@ -10,6 +10,7 @@ import {PackageSpec} from '../install'
 /**
  * Resolves a package in the NPM registry. Done as part of `install()`.
  *
+ * @example
  *     var npa = require('npm-package-arg')
  *     resolve(npa('rimraf@2'))
  *       .then((res) => {
@@ -88,10 +89,10 @@ function pickVersionFromRegistryDocument (pkg: PackageDocument, dep: PackageSpec
 /**
  * Converts package data (from `npa()`) to a URI
  *
+ * @example
  *     toUri({ name: 'rimraf', rawSpec: '2' })
  *     // => 'https://registry.npmjs.org/rimraf/2'
  */
-
 function toUri (spec: PackageSpec) {
   let name: string
 

src/resolve/tarball.ts

@@ -6,6 +6,7 @@ import {ResolveResult} from '.'
 /**
  * Resolves a 'remote' package.
  *
+ * @example
  *     pkg = {
  *       raw: 'http://registry.npmjs.org/is-array/-/is-array-1.0.1.tgz',
  *       scope: null,

src/runtimeError.ts

@@ -1,8 +1,7 @@
-/*
+/**
  * An error message with a `silent` flag, where the stack is supressed.
  * Used for user-friendly error messages.
  */
-
 export default function runtimeError (message: string) {
   const err = new Error(message)
   err['silent'] = true