How do I use ngdoc to document an 'angular factory' that returns a 'factory function'? Specifically, how do I document the objects my 'factory function' creates?
In the contrived example below I've documented how to use the factory to create a page object, but how do I document how to use the page objects themselves?
angular.module('fooRestClient').factory('page', function () {
var prototype = {};
// Below I need to somehow link the methods a page object has to the
// factory's documentation.
/**
* @description Fetches the page at the specified index.
*
* @param {number} index - the index of the page to fetch
*
* @returns {object} a page object representing the page at the given index
*/
prototype.getPage = function (index) {
// returns a new page.
};
// ... more useful methods.
/**
* @ngdoc service
* @type function
* @name fooRestClient:page
* @description
* A factory function for producing page objects....
*
* @param {Number} index - The page index.
* @param {Number} size - The page size.
* @param {Number} total - The total number of pages.
* @param {Array} data - The contents of the page.
* @returns {object} A page object for the given resource
*/
return function page(index, size, total, data) {
return Object.create(prototype, {
index: index,
size: size,
total: total,
data: data
});
};
});
The closest match I can find on SO is: How to document a factory that returns a class in angular with ngdoc?. This doesn't help because I don't have a "class" name to link the methods back to as I'm not using pseudo-classical inheritance.
Maybe this works as you expect:
I know its a bit verbose, but it's the only way I found to do this kind of things