message: clean up auth core session docs & mark as deprecated
diff: /* @flow */
  import { TokenSigner, decodeToken, SECP256K1Client } from 'jsontokens'
  import fetch from 'isomorphic-fetch'
  -/*
  +
  +/**
  * Create an authentication token to be sent to the Core API server
  * in order to generate a Core session JWT.
  *
  - * @param appDomain (String) The unique application identifier (e.g. foo.app, www.foo.com, etc).
  - * @param appMethods (Array) The list of API methods this application will need.
  - * @param appPrivateKey (String) The application-specific private key
  - * @param blockchainId (String|null) This is the blockchain ID of the requester,
  + * @param {String} appDomain The unique application identifier (e.g. foo.app, www.foo.com, etc).
  + * @param {Array} appMethods The list of API methods this application will need.
  + * @param {String} appPrivateKey The application-specific private key
  + * @param {String|null} blockchainID This is the blockchain ID of the requester
  + * @param {String} thisDevice Identifier of the current device
  *
  - * @returns a JWT signed by the app's private key
  + * @return {String} a JWT signed by the app's private key
  + * @deprecated
  * @private
  */
  export function makeCoreSessionRequest(appDomain: string,
  @@ -47,14 +50,18 @@ export function makeCoreSessionRequest(appDomain: string,
  }
  -/*
  +/**
  * Send Core a request for a session token.
  *
  - * @param coreAuthRequest (String) a signed JWT encoding the authentication request
  - * @param apiPassword (String) the API password for Core
  + * @param {String} coreHost host name of the core node
  + * @param {Number} corePort port number of the core node
  + * @param {String} coreAuthRequest a signed JWT encoding the authentication request
  + * @param {String} apiPassword the API password for Core
  *
  - * Returns a JWT signed with the Core API server's private key that authorizes the bearer
  - * to carry out the requested operations.
  + * @return {Promise} the resolves to a JWT signed with the Core API server's private key
  + * that authorizes the bearer to carry out the requested operations and rejects
  + * with an error message otherwise
  + * @deprecated
  * @private
  */
  export function sendCoreSessionRequest(coreHost: string,
  @@ -101,17 +108,22 @@ export function sendCoreSessionRequest(coreHost: string,
  }
  -/*
  +/**
  * Get a core session token. Generate an auth request, sign it, send it to Core,
  * and get back a session token.
  *
  - * @param coreHost (String) Core API server's hostname
  - * @param corePort (Integer) Core API server's port number
  - * @param appPrivateKey (String) Application's private key
  - * @param blockchainId (String|null) blockchain ID of the user signing in.
  + * @param {String} coreHost Core API server's hostname
  + * @param {Number} corePort Core API server's port number
  + * @param {String} apiPassword core api password
  + * @param {String} appPrivateKey Application's private key
  + * @param {String} blockchainId blockchain ID of the user signing in.
  * `null` if user has no blockchain ID
  + * @param {String} authRequest authentication request token
  + * @param {String} deviceId identifier for the current device
  *
  - * Returns a Promise that resolves to a Core session token.
  + * @return {Promise} a Promise that resolves to a Core session token or rejects
  + * with an error message.
  + * @deprecated
  * @private
  */
  export function getCoreSession(coreHost: string,
  