API doc notes

Table of Contents Things I did Questions Validation functions Missing Stuff Discovery functions Other questions

Things I did

Changes on 3/12/14:

• Updated a bunch of .js files to fix formatting. See commit.
• Copied content from markdown files in LoopBack repo into JSDoc comments in this repo:
  • api-datasource.md
  • api-geopoint.md
  • api-model.md
• Reformatted docs.json and moved the following from docs.json:
  • hooks.js
  • types.js

Questions

Validation functions

How to document validation functions in validations.js? User will see functions like ```.validatesNumericalityOf()```

For example, signature is either

@param {String} fieldName Name of field (property) to validate
@options {Object} Validation configuration options
@prop {Number} min Minimum allowed value
@prop {Number} max Maximum allowed value
@prop {Number} is Must have this value.
@prop {Object} Object with a single key, 'message' whose value is the error message.

OR

@param {String} fieldName Name of field (property) to validate
@options {Object} Validation configuration options
@prop {Number} min Minimum allowed value
@prop {Number} max Maximum allowed value
@prop {Number} is Must have this value.
@prop {Object} Object with a single key, 'message' whose value is an object with keys corresponding to the configuration option key names (e.g ```message: {min: 'too short', max: 'too long'}``` ) .

Validatable.validatesNumericalityOf

Missing Stuff

• Comments at beginnning of loopback/lib/acl.js are not being parsed properly. Are the things like accessType and permission properties? There appear to be other issues re JSDoc comments in this file.

Discovery functions

Functions like discoverForeignKeys and discoverPrimaryKeys are implemented in datasource-juggler as well as in loopback-connector-oracle. Do we need to doc both? Or can we simply refer to the former for Oracle and MySQL?

In Oracle discovery API, the tests say the functions return arrays of values. But md doc lists JSON like this:

          { owner: 'STRONGLOOP',
            tableName: 'PRODUCT',
            columnName: 'ID',
            dataType: 'VARCHAR2',
            dataLength: 20,
            nullable: 'N',
            type: 'String' }
          { owner: 'STRONGLOOP',
            tableName: 'PRODUCT',
            columnName: 'NAME',
            dataType: 'VARCHAR2',
            dataLength: 64,
            nullable: 'Y',
            type: 'String' }

Is it an array or an object, or something else?

Other questions

• Why is ModelClass.registerProperty() included in ModelBuilder.js. Should it be part of it's own class API doc?
• Is defineReadonlyProp() a method of DataAccessObject? It doesn't appear to be defined that way? Is it just an internal function that shouldn't be documented?
• I'm a bit confused about what stuff should go into the API doc for LoopBack and what should go into LoopBack DataSource Juggler.

In loopback-connector-oracle, following functions were not documented in md file; should they be?:

• isActual
• alterTable
• dropTable
• createTable
• disconnect