Update Documentation for Wrappers (hyperledger-archives#445)

* Adds Documentation Steps for Node * Adds generate Docs for Python * Updates python gitignore * Adds documentation for Connection and vcx init for both wrappers * Updates All Node Wrapper Functions for Documentation * Updates All Python Wrapper Functions for Documentation * Fixes Description for Proof.create Function * Updates per Review Comments * Ignore Mocked Accepted Connection Test for Node * Updates Docs * Adds Script for Generating Python Docs Signed-off-by: Mark Hadley <[email protected]>
srottem · Aug 14, 2018 · 391b344 · 391b344
1 parent 25f3182
commit 391b344
Show file tree

Hide file tree

Showing 19 changed files with 843 additions and 198 deletions.
diff --git a/vcx/wrappers/node/README.md b/vcx/wrappers/node/README.md
@@ -1,3 +1,4 @@
+
 # VCX NodeJS Wrapper
 
 ## Contribution Guide
@@ -18,3 +19,13 @@ Run this commands before submitting your PR:
 ```
 npm run lint
 ```
+
+## Documentation:
+ Run these commands:
+```
+npm install
+npm ci
+npm doc-gen
+```
+* A directory will be created locally `./docs` which contains an `index.html` file which can be used to navigate the generated documents.
+
diff --git a/vcx/wrappers/node/package.json b/vcx/wrappers/node/package.json
@@ -36,7 +36,7 @@
     "scripts": {
         "compile": "./node_modules/.bin/tsc -p ./tsconfig.json",
         "lint": "./node_modules/.bin/tslint --type-check -c ./tslint.json -p ./tsconfig.json && ./node_modules/.bin/tslint --type-check -c ./test/tslint.json -p ./test/tsconfig.json",
-        "doc-gen": "./node_modules/.bin/jsdoc -r -d doc dist/*",
+        "doc-gen": "./node_modules/.bin/typedoc --out doc --excludePrivate --excludeProtected --ignoreCompilerErrors src",
         "test": "export TS_NODE_PROJECT=\"./test/tsconfig.json\" export NODE_ENV='test' && export RUST_LOG=\"trace\" && export RUST_BACKTRACE=full && ./node_modules/.bin/mocha --timeout 10000 -gc --expose-gc --exit --recursive --use_strict --require ts-node/register ./test/suite1/**/*.test.ts && ./node_modules/.bin/mocha --timeout 10000 -gc --expose-gc --exit --recursive --use_strict --require ts-node/register ./test/suite2/**/*.test.ts"
     },
     "devDependencies": {
@@ -53,6 +53,7 @@
         "ts-node": "^6.1.2",
         "tslint": "^5.8.0",
         "tslint-config-standard": "^7.1.0",
+        "typedoc": "0.11.1",
         "typescript": "^2.9.1"
     },
     "main": "dist/index.js",

diff --git a/vcx/wrappers/node/src/api/connection.ts b/vcx/wrappers/node/src/api/connection.ts
@@ -42,15 +42,14 @@ export interface IConnectOptions {
  */
 export class Connection extends VCXBaseWithState<IConnectionData> {
   /**
-   * @memberof Connection
-   * @description Builds a generic Connection object.
-   * @static
-   * @async
-   * @function create
-   * @param {IConnectionCreateData} recipientInfo
-   * @example <caption>Example of recipientInfo</caption>
-   * {id: "123"}
-   * @returns {Promise<Connection>} A Connection Object
+   * Create a connection object, represents a single endpoint and can be used for sending and receiving
+   * credentials and proofs
+   *
+   * Example:
+   * ```
+   * source_id = 'foobar123'
+   * connection = await Connection.create(source_id)
+   * ```
    */
   public static async create ({ id }: IConnectionCreateData): Promise<Connection> {
     try {
@@ -64,15 +63,15 @@ export class Connection extends VCXBaseWithState<IConnectionData> {
   }
 
   /**
-   * @memberof Connection
-   * @description Builds a generic Connection object.
-   * @static
-   * @async
-   * @function create
-   * @param {IConnectionCreateData} recipientInfo
-   * @example <caption>Example of recipientInfo</caption>
-   * {id: "123"}
-   * @returns {Promise<Connection>} A Connection Object
+   * Create a connection object with a provided invite, represents a single endpoint and can be used for
+   * sending and receiving credentials and proofs.
+   * Invite details are provided by the entity offering a connection and generally pulled from a provided QRCode.
+   *
+   * Example:
+   * ```
+   * sourceId = 'foobar123'
+   * connection_handle = await Connection.createWithInvite({sourceId, inviteDetails})
+   * ```
    */
   public static async createWithInvite ({ id, invite }: IRecipientInviteInfo): Promise<Connection> {
     const connection = new Connection(id)
@@ -88,18 +87,10 @@ export class Connection extends VCXBaseWithState<IConnectionData> {
   }
 
   /**
-   * @memberof Connection
-   * @description Builds a Connection object with defined attributes.
-   * The attributes are often provided by a previous call to the serialize function
-   * @static
-   * @async
-   * @function deserialize
-   * @param {ISerializedData<IConnectionData>} connectionData - contains the information
-   * that will be used to build a connection object
-   * @example <caption>Example of Connection Data </caption>
-   * {source_id:"234",handle:560373036,pw_did:"did",pw_verkey:"verkey",did_endpoint:"",state:2,uuid:"",endpoint:"",
-   * invite_detail:{e:"",rid:"",sakdp:"",sn:"",sD:"",lu:"",sVk:"",tn:""}}
-   * @returns {Promise<Connection>} A Connection Object
+   * Create the object from a previously serialized object.
+   * Example:
+   * data = await connection1.serialize()
+   * connection2 = await Connection.deserialize(data)
    */
   public static async deserialize (connectionData: ISerializedData<IConnectionData>) {
     const connection = await super._deserialize(Connection, connectionData)
@@ -114,10 +105,13 @@ export class Connection extends VCXBaseWithState<IConnectionData> {
   protected _inviteDetailFn = rustAPI().vcx_connection_invite_details
 
   /**
-   * @memberof Connection
-   * @description Deletes and releases a connection
-   * @function delete
-   * @returns {Promis<void>}
+   * Delete the object from the agency and release any memory associated with it
+   *
+   * Example:
+   * ```
+   * def connection = await Connection.create(source_id)
+   * await connection.delete()
+   * ```
    */
   public async delete (): Promise<void> {
     try {
@@ -148,8 +142,9 @@ export class Connection extends VCXBaseWithState<IConnectionData> {
    *
    * Example:
    * ```
-   * connection = await Connection.create({id: 'foobar'})
-   * inviteDetails = await connection.connect()
+   * phoneNumber = '8019119191'
+   * connection = await Connection.create('foobar123')
+   * inviteDetails = await connection.connect({phone: phoneNumber})
    * ```
    * @returns {Promise<string}
    */
@@ -185,12 +180,15 @@ export class Connection extends VCXBaseWithState<IConnectionData> {
   }
 
   /**
-   * @memberof Connection
-   * @description
    * Gets the details of the invitation that was returned from the Agent Service.
-   * @async
-   * @function inviteDetails
-   * @returns {Promise<string>} - String with the details
+   *
+   * Example:
+   * ```
+   * phoneNumber = '8019119191'
+   * connection = await Connection.create('foobar123')
+   * inviteDetails = await connection.connect({phone: phoneNumber})
+   * inivteDetailsAgain = await connection.inviteDetails()
+   * ```
    */
   public async inviteDetails (abbr: boolean = false): Promise<IConnectionInvite> {
     try {

diff --git a/vcx/wrappers/node/src/api/credential-def.ts b/vcx/wrappers/node/src/api/credential-def.ts
@@ -51,21 +51,19 @@ export class CredentialDefPaymentManager extends PaymentManager {
  */
 export class CredentialDef extends VCXBase<ICredentialDefData> {
   /**
-   * @memberof CredentialDef
-   * creates a credential definition on the ledger and returns an associated object.
-   * @static
-   * @async
-   * @function create
-   * @param {ICredentialDefCreateData} data
-   * @example <caption>Example of ICredentialDefinition</caption>
-   * {
-   *    sourceId: "12",
-   *    schemaId: "2hoqvcwupRTUNkXn6ArYzs:2:test-licence:4.4.4",
-   *    name: "test-licence",
-   *    revocation: false,
-   *    paymentHandle: 0
+   * Creates a new CredentialDef object that is written to the ledger
+   *
+   * Example:
+   * ```
+   * data = {
+   *   name: 'testCredentialDefName',
+   *   paymentHandle: 0,
+   *   revocation: false,
+   *   schemaId: 'testCredentialDefSchemaId',
+   *   sourceId: 'testCredentialDefSourceId'
    * }
-   * @returns {Promise<CredentialDef>} A credentialDef Object
+   * credentialDef = await CredentialDef.create(data)
+   * ```
    */
   public static async create ({
     name,
@@ -96,15 +94,21 @@ export class CredentialDef extends VCXBase<ICredentialDefData> {
   }
 
   /**
-   * @memberof CredentialDef
-   * @description Builds a credentialDef object with defined attributes.
+   * Builds a credentialDef object with defined attributes.
    * Attributes are provided by a previous call to the serialize function.
-   * @static
-   * @async
-   * @function deserialize
-   * @param {ISerialziedData<ICredentialDefData>} data - data obtained by serialize api.
-   * Used to build a credentialdef object.
-   * @returns {Promise<credentialDef>} A credentialDef Object
+   * Example:
+   * ```
+   * data = {
+   *   name: 'testCredentialDefName',
+   *   paymentHandle: 0,
+   *   revocation: false,
+   *   schemaId: 'testCredentialDefSchemaId',
+   *   sourceId: 'testCredentialDefSourceId'
+   * }
+   * credentialDef = await CredentialDef.create(data)
+   * data1 = await credentialDef.serialize()
+   * credentialDef2 = await CredentialDef.deserialzie(data1)
+   * ```
    */
   public static async deserialize (credentialDef: ISerializedData<ICredentialDefData>) {
     // Todo: update the ICredentialDefObj
@@ -132,11 +136,19 @@ export class CredentialDef extends VCXBase<ICredentialDefData> {
   }
 
   /**
-   * @memberof CredentialDef
-   * @description Retrieves the credential definition id associated with the created cred def.
-   * @async
-   * @function getCredDefId
-   * @returns {Promise<string>} - CredDef's Identifier
+   * Retrieves the credential definition id associated with the created cred def.
+   * Example:
+   * ```
+   * data = {
+   *   name: 'testCredentialDefName',
+   *   paymentHandle: 0,
+   *   revocation: false,
+   *   schemaId: 'testCredentialDefSchemaId',
+   *   sourceId: 'testCredentialDefSourceId'
+   * }
+   * credentialDef = await CredentialDef.create(data)
+   * id = await credentialDef.getCredDefId()
+   * ```
    */
   public async getCredDefId (): Promise<string> {
     try {

diff --git a/vcx/wrappers/node/src/api/credential.ts b/vcx/wrappers/node/src/api/credential.ts
@@ -98,6 +98,7 @@ export class Credential extends VCXBaseWithState<ICredentialStructData> {
   }
 
   /**
+   * Create a Credential object that requests and receives a credential for an institution
    *
    * ```
    * credential = Credential.createWithMsgId({
@@ -106,8 +107,6 @@ export class Credential extends VCXBaseWithState<ICredentialStructData> {
    *   sourceId: 'testCredentialSourceId'
    * })
    * ```
-   *
-   *
    */
   public static async createWithMsgId (
     { connection, sourceId, msgId }: ICredentialCreateWithMsgId

diff --git a/vcx/wrappers/node/src/api/init.ts b/vcx/wrappers/node/src/api/init.ts
@@ -5,6 +5,15 @@ import { initRustAPI, rustAPI } from '../rustlib'
 import { createFFICallbackPromise } from '../utils/ffi-helpers'
 import { IInitVCXOptions } from './common'
 
+/**
+ * Initializes VCX with config file.
+ * An example config file is at libvcx/sample_config/config.json
+ *
+ * Example:
+ * ```
+ * await initVcx('/home/username/vcxconfig.json')
+ * ```
+ */
 export async function initVcx (configPath: string, options: IInitVCXOptions = {}): Promise<void> {
   initRustAPI(options.libVCXPath)
   let rc = null
@@ -32,6 +41,29 @@ export async function initVcx (configPath: string, options: IInitVCXOptions = {}
   }
 }
 
+/**
+ * Initializes VCX with config file.
+ * An example config file is at libvcx/sample_config/config.json
+ *
+ * Example:
+ * ```
+ * config = {
+ *   "agency_did": "L5nbFwXJRmdnJVYhCsy52j",
+ *   "agency_verkey": "BQEgx9PJ7JJgt1LadyP45a7JrWdyqkrzrCBGRZ9QVrvL",
+ *   "agency_endpoint": "https://cagency.pdev.evernym.com",
+ *   "genesis_path":"/var/lib/indy/verity-staging/pool_transactions_genesis",
+ *   "institution_name": "institution",
+ *   "institution_logo_url": "http://robohash.org/234",
+ *   "institution_did": "EwsFhWVoc3Fwqzrwe998aQ",
+ *   "institution_verkey": "8brs38hPDkw5yhtzyk2tz7zkp8ijTyWnER165zDQbpK6",
+ *   "remote_to_sdk_did": "EtfeMFytvYTKnWwqTScp9D",
+ *   "remote_to_sdk_verkey": "8a7hZDyJK1nNCizRCKMr4H4QbDm8Gg2vcbDRab8SVfsi",
+ *   "sdk_to_remote_did": "KacwZ2ndG6396KXJ9NDDw6",
+ *   "sdk_to_remote_verkey": "B8LgZGxEPcpTJfZkeqXuKNLihM1Awm8yidqsNwYi5QGc"
+ *  }
+ * await initVcxWithConfig('/home/username/vcxconfig.json')
+ * ```
+ */
 export async function initVcxWithConfig (config: string, options: IInitVCXOptions = {}): Promise<void> {
   initRustAPI(options.libVCXPath)
   let rc = null