' + str + ''; 16 | } 17 | 18 | return str; 19 | }; 20 | }; -------------------------------------------------------------------------------- /jsdoc/tag-defs/index.js: -------------------------------------------------------------------------------- 1 | 2 | module.exports = [ 3 | require('./name'), 4 | require('./memberof'), 5 | require('./param'), 6 | require('./property'), 7 | require('./returns'), 8 | require('./type'), 9 | require('./requires'), 10 | require('./module'), 11 | require('./description'), 12 | require('./deprecated'), 13 | require('./private'), 14 | require('./see'), 15 | require('./usage'), 16 | require('./animations'), 17 | require('./constructor'), 18 | require('./class'), 19 | require('./classdesc'), 20 | require('./global'), 21 | require('./namespace'), 22 | require('./kind'), 23 | require('./function'), 24 | require('./method') 25 | ]; 26 | -------------------------------------------------------------------------------- /ngdoc/services/getTypeClass.spec.js: -------------------------------------------------------------------------------- 1 | var getTypeClassFactory = require('./getTypeClass'); 2 | 3 | describe("getTypeClass", function() { 4 | it("should convert the type name to a css string", function() { 5 | var getTypeClass = getTypeClassFactory(); 6 | expect(getTypeClass('string')).toEqual('label type-hint type-hint-string'); 7 | expect(getTypeClass('Object')).toEqual('label type-hint type-hint-object'); 8 | expect(getTypeClass('')).toEqual('label type-hint type-hint-object'); 9 | expect(getTypeClass('function() {}')).toEqual('label type-hint type-hint-function'); 10 | expect(getTypeClass('array.
| Name | 19 |Description | 20 |
|---|---|
| {$ page.id | link(page.name, page) $} | 24 |{$ page.description | firstParagraph | marked $} | 25 |
' + value + ''; });
9 | codeFilter = codeFilterFactory(codeSpy);
10 | });
11 |
12 | it("should have the name 'code'", function() {
13 | expect(codeFilter.name).toEqual('code');
14 | });
15 |
16 |
17 | it("should call the code utility", function() {
18 | codeFilter.process('function foo() { }');
19 | expect(codeSpy).toHaveBeenCalledWith('function foo() { }', true, undefined);
20 | });
21 |
22 |
23 | it("should pass the language to the code utility", function() {
24 | codeFilter.process('function foo() { }', 'js');
25 | expect(codeSpy).toHaveBeenCalledWith('function foo() { }', true, 'js');
26 | });
27 | });
--------------------------------------------------------------------------------
/jsdoc/file-readers/jsdoc.js:
--------------------------------------------------------------------------------
1 | var _ = require('lodash');
2 | var esprima = require('esprima');
3 |
4 | /**
5 | * @dgService jsdocFileReader
6 | * @description
7 | * This file reader will create a simple doc for each js
8 | * file including a code AST of the JavaScript in the file.
9 | */
10 | module.exports = function jsdocFileReader(log) {
11 | return {
12 | name: 'jsdocFileReader',
13 | defaultPattern: /\.js$/,
14 | getDocs: function(fileInfo) {
15 |
16 | try {
17 | fileInfo.ast = esprima.parse(fileInfo.content, {
18 | loc: true,
19 | attachComment: true
20 | });
21 | } catch(ex) {
22 | ex.file = fileInfo.filePath;
23 | throw new Error(
24 | _.template('JavaScript error in file "${file}"" [line ${lineNumber}, column ${column}]: "${description}"', ex));
25 | }
26 |
27 | return [{
28 | docType: 'jsFile'
29 | }];
30 | }
31 | };
32 | };
--------------------------------------------------------------------------------
/jsdoc/processors/code-name.spec.js:
--------------------------------------------------------------------------------
1 | var codeNameProcessorFactory = require('./code-name');
2 | var jsParser = require('esprima');
3 |
4 | var mockLog = jasmine.createSpyObj('log', ['error', 'warn', 'info', 'debug', 'silly']);
5 |
6 | describe('code-name doc processor', function() {
7 | it("should understand CallExpressions", function() {
8 | var processor = codeNameProcessorFactory(mockLog);
9 | var ast = jsParser.parse('(function foo() { })()');
10 | var doc = { codeNode: ast };
11 | processor.$process([doc]);
12 | expect(doc.codeName).toEqual('foo');
13 | });
14 |
15 | it("should understand ArrayExpressions", function() {
16 | var processor = codeNameProcessorFactory(mockLog);
17 | var ast = jsParser.parse("$CompileProvider.$inject = ['$provide', '$$sanitizeUriProvider'];");
18 | var doc = { codeNode: ast };
19 | processor.$process([doc]);
20 | expect(doc.codeName).toEqual('$inject');
21 | });
22 |
23 | });
--------------------------------------------------------------------------------
/nunjucks/services/renderMarkdown.js:
--------------------------------------------------------------------------------
1 | var marked = require('marked');
2 |
3 | /**
4 | * @dgService renderMarkdown
5 | * @description
6 | * Render the markdown in the given string as HTML.
7 | */
8 | module.exports = function renderMarkdown(trimIndentation) {
9 |
10 | var renderer = new marked.Renderer();
11 |
12 | // remove the leading whitespace from the code block before it gets to the
13 | // markdown code render function
14 | renderer.code = function(code, string, language) {
15 |
16 | var trimmedCode = trimIndentation(code);
17 | var renderedCode = marked.Renderer.prototype.code.call(this, trimmedCode, string, language);
18 |
19 | // Bug in marked - forgets to add a final newline sometimes
20 | if ( !/\n$/.test(renderedCode) ) {
21 | renderedCode += '\n';
22 | }
23 |
24 | return renderedCode;
25 | };
26 |
27 | return function(content) {
28 | return marked(content, { renderer: renderer });
29 | };
30 | };
--------------------------------------------------------------------------------
/jsdoc/services/transforms/extract-type.spec.js:
--------------------------------------------------------------------------------
1 | var transformFactory = require('./extract-type');
2 |
3 | describe("extract-type transform", function() {
4 |
5 | var transform;
6 |
7 | beforeEach(function() {
8 | doc = {};
9 | tag = {};
10 | transform = transformFactory();
11 | });
12 |
13 | it("should extract the type from the description", function() {
14 |
15 | value = ' {string} paramName - Some description \n Some more description';
16 | value = transform(doc, tag, value);
17 |
18 | expect(tag.typeList).toEqual(['string']);
19 | expect(value).toEqual('paramName - Some description \n Some more description');
20 | });
21 |
22 | it("should return the description if no type is found", function() {
23 | value = 'paramName - Some description \n Some more description';
24 | value = transform(doc, tag, value);
25 | expect(value).toEqual('paramName - Some description \n Some more description');
26 | });
27 | });
--------------------------------------------------------------------------------
/jsdoc/tag-defs/description.spec.js:
--------------------------------------------------------------------------------
1 | var tagDefFactory = require('./description');
2 |
3 | describe("description tag-def", function() {
4 | var tagDef;
5 |
6 | beforeEach(function() {
7 | tagDef = tagDefFactory();
8 | });
9 |
10 | describe('transforms', function() {
11 | it("should prepend any non-tag specific description found in the jsdoc comment", function() {
12 | var doc = { tags: { description: 'general description'} };
13 | var tag = {};
14 | var value = "tag specific description";
15 | expect(tagDef.transforms(doc, tag, value)).toEqual('general description\ntag specific description');
16 | });
17 | });
18 |
19 |
20 | describe("defaultFn", function() {
21 | it("should get the contents of the non-tag specific description", function() {
22 | var doc = { tags: { description: 'general description'} };
23 | expect(tagDef.defaultFn(doc)).toEqual('general description');
24 | });
25 | });
26 | });
--------------------------------------------------------------------------------
/examples/inline-tag-defs/runnableExample.js:
--------------------------------------------------------------------------------
1 | /**
2 | * @dgService runnableExampleInlineTagDef
3 | * @description
4 | * Inject the specified runnable example into the doc
5 | */
6 | module.exports = function runnableExampleInlineTagDef(exampleMap, createDocMessage) {
7 | return {
8 | name: 'runnableExample',
9 |
10 | handler: function(doc, tagName, description) {
11 |
12 | // The tag description should contain the id of the runnable example doc
13 | var example = exampleMap.get(description);
14 | if ( !example ) {
15 | throw new Error(createDocMessage('No example exists with id "' + description + '".', doc));
16 | }
17 | if ( !example.runnableExampleDoc ) {
18 | throw new Error(createDocMessage('Example "' + description + '" does not have an associated runnableExampleDoc. Are you missing a processor (examples-generate)?"', doc));
19 | }
20 |
21 | return example.runnableExampleDoc.renderedContent;
22 | }
23 | };
24 | };
--------------------------------------------------------------------------------
/base/services/createDocMessage.js:
--------------------------------------------------------------------------------
1 | module.exports = function createDocMessage() {
2 | return function(message, doc, error) {
3 | message = message || '';
4 | if ( doc ) {
5 | message += ' - doc';
6 | var docIdentifier = doc.id || doc.name || doc.path;
7 | if ( docIdentifier ) {
8 | message += ' "' + docIdentifier + '"';
9 | }
10 | if ( doc.docType ) {
11 | message += ' (' + doc.docType + ') ';
12 | }
13 | var filePath = doc.fileInfo && doc.fileInfo.relativePath;
14 | if ( filePath ) {
15 | message += ' - from file "' + filePath + '"';
16 | if ( doc.startingLine ) {
17 | message += ' - starting at line ' + doc.startingLine;
18 | }
19 | if ( doc.endingLine ) {
20 | message += ', ending at line ' + doc.endingLine;
21 | }
22 | }
23 | }
24 | if ( error ) {
25 | message += '\n\nOriginal Error: \n\n' + error.stack;
26 | }
27 | return message;
28 | };
29 | };
--------------------------------------------------------------------------------
/nunjucks/rendering/tags/marked.js:
--------------------------------------------------------------------------------
1 | /**
2 | * @dgRenderTag marked
3 | * @description Convert a block of template text from markdown to HTML
4 | */
5 | module.exports = function markedNunjucksTag(trimIndentation, renderMarkdown) {
6 | return {
7 | tags: ['marked'],
8 |
9 | parse: function(parser, nodes) {
10 | parser.advanceAfterBlockEnd();
11 |
12 | var content = parser.parseUntilBlocks("endmarked");
13 | var tag = new nodes.CallExtension(this, 'process', null, [content]);
14 | parser.advanceAfterBlockEnd();
15 |
16 | return tag;
17 | },
18 |
19 | process: function(context, content) {
20 | var contentString = content();
21 | var indent = trimIndentation.calcIndent(contentString);
22 | var trimmedString = trimIndentation.trimIndent(contentString, indent);
23 | var markedString = renderMarkdown(trimmedString);
24 | var reindentedString = trimIndentation.reindent(markedString, indent);
25 | return reindentedString;
26 | }
27 | };
28 | };
--------------------------------------------------------------------------------
/base/processors/debugDumpProcessor.spec.js:
--------------------------------------------------------------------------------
1 | var path = require('canonical-path');
2 | var Q = require('q');
3 |
4 | var mockPackage = require('../mocks/mockPackage');
5 | var Dgeni = require('dgeni');
6 |
7 |
8 | describe("debugDumpProcessor", function() {
9 | it("should write out the docs to a file", function() {
10 |
11 | var writeFileSpy = jasmine.createSpy('writeFile').and.returnValue(Q());
12 | var testPackage = mockPackage().factory('writeFile', function() { return writeFileSpy; });
13 |
14 | var dgeni = new Dgeni([testPackage]);
15 | var injector = dgeni.configureInjector();
16 |
17 | var readFilesProcessor = injector.get('readFilesProcessor');
18 | readFilesProcessor.basePath = path.resolve('some/path');
19 |
20 | var processor = injector.get('debugDumpProcessor');
21 |
22 | processor.outputPath = 'build/dump.txt';
23 | processor.$process([{ val: 'a' }, { val: 'b' }]);
24 | expect(writeFileSpy).toHaveBeenCalledWith(path.resolve('some/path/build/dump.txt'), "[ { val: 'a' }, { val: 'b' } ]");
25 | });
26 | });
--------------------------------------------------------------------------------
/base/services/extractLinks.js:
--------------------------------------------------------------------------------
1 | var htmlparser = require("htmlparser2");
2 |
3 | /**
4 | * @dgService extractLinks
5 | * @description
6 | * Extracts the links and references from a given html
7 | * @param {String} html The html
8 | */
9 | module.exports = function extractLinks() {
10 | return function(html) {
11 | var result = {hrefs: [], names: []};
12 | var parser = new htmlparser.Parser({
13 | onopentag: function(name, attribs) {
14 |
15 | // Parse anchor elements, extracting href and name
16 | if (name === 'a') {
17 | if (attribs.href) {
18 | result.hrefs.push(attribs.href);
19 | }
20 | if (attribs.name) {
21 | result.names.push(attribs.name);
22 | }
23 | }
24 |
25 | // Extract id from other elements
26 | if(attribs.id) {
27 | result.names.push(attribs.id);
28 | }
29 | }
30 | }, {
31 | decodeEntities: true
32 | });
33 | parser.write(html);
34 | parser.end();
35 | return result;
36 | };
37 | };
38 |
--------------------------------------------------------------------------------
/examples/inline-tag-defs/runnableExample.spec.js:
--------------------------------------------------------------------------------
1 | var mockPackage = require('../mocks/mockPackage');
2 | var Dgeni = require('dgeni');
3 |
4 | describe("runnableExampleInlineTagDef", function() {
5 |
6 | var exampleMap, tagDef;
7 |
8 | beforeEach(function() {
9 | var dgeni = new Dgeni([mockPackage()]);
10 | var injector = dgeni.configureInjector();
11 |
12 | exampleMap = injector.get('exampleMap');
13 | exampleMap.set('some-example', {
14 | runnableExampleDoc: {
15 | renderedContent: 'The rendered content of the some-example example'
16 | }
17 | });
18 | tagDef = injector.get('runnableExampleInlineTagDef');
19 | });
20 |
21 | it("should have the correct name", function() {
22 | expect(tagDef.name).toEqual('runnableExample');
23 | });
24 |
25 | it("should lookup the runnableExampleDoc identified in the tag description and return its renderedContent", function() {
26 | expect(tagDef.handler({}, 'runnableExample', 'some-example')).toEqual('The rendered content of the some-example example');
27 | });
28 | });
--------------------------------------------------------------------------------
/examples/templates/runnableExample.template.html:
--------------------------------------------------------------------------------
1 | {# Be aware that we need these extra new lines here or marked will not realise that the - thus breaking the HTML #} 3 | 4 | 5 |
- thus breaking the HTML #} -------------------------------------------------------------------------------- /base/services/resolveUrl.js: -------------------------------------------------------------------------------- 1 | var url = require('url'); 2 | var path = require('canonical-path'); 3 | 4 | /** 5 | * @dgService resolveUrl 6 | * @description 7 | * Calculates the absolute path of the url from the current path, 8 | * the relative path and the base 9 | * @param {String=} currentPath The current path 10 | * @param {String} newPath The new path 11 | * @param {String=} base The base path 12 | */ 13 | module.exports = function resolveUrl() { 14 | return function(currentPath, newPath, base) { 15 | 16 | // Extract only the path and the hash from the newPath 17 | var parsedUrl = url.parse(newPath); 18 | parsedUrl.search = null; 19 | newPath = url.format(parsedUrl); 20 | 21 | if ( base && newPath.charAt(0) !== '/' ) { 22 | // Resolve against the base url if there is a base and the new path is not absolute 23 | newPath = path.resolve(base, newPath).substr(1); 24 | } else { 25 | // Otherwise resolve against the current path 26 | newPath = url.resolve(currentPath || '', newPath); 27 | } 28 | 29 | return newPath; 30 | }; 31 | }; 32 | -------------------------------------------------------------------------------- /ngdoc/rendering/tags/code.spec.js: -------------------------------------------------------------------------------- 1 | var codeTagFactory = require('./code'); 2 | var nunjucks = require('nunjucks'); 3 | 4 | describe("code custom tag", function() { 5 | var codeTag, trimIndentationSpy, codeSpy, env; 6 | 7 | beforeEach(function() { 8 | trimIndentationSpy = jasmine.createSpy('trimIndentation').and.callFake(function(value) { return value.trim(); }); 9 | codeSpy = jasmine.createSpy('code'); 10 | codeTag = codeTagFactory(trimIndentationSpy, codeSpy); 11 | 12 | env = nunjucks.configure('views'); 13 | env.addExtension(codeTag.tags[0], codeTag); 14 | }); 15 | 16 | it("should pass the content to the code utility", function() { 17 | env.renderString('\n{% code %}\nfunction() {}\n{% endcode %}\n'); 18 | expect(codeSpy).toHaveBeenCalledWith('function() {}', false, undefined); 19 | }); 20 | 21 | it("should pass the language if provided to the code utility", function() { 22 | env.renderString('\n{% code lang %}\nfunction() {}\n{% endcode %}\n', { lang: 'js' }); 23 | expect(codeSpy).toHaveBeenCalledWith('function() {}', false, 'js'); 24 | }); 25 | }); -------------------------------------------------------------------------------- /jsdoc/services/transforms/extract-name.js: -------------------------------------------------------------------------------- 1 | // Matches: 2 | // name, [name], [name=default], name text, [name] text, [name=default] text, name - text, [name] - text or [name=default] - text 3 | var NAME_AND_DESCRIPTION = /^\s*(\[([^\]=]+)(?:=([^\]]+))?\]|\S+)((?:[ \t]*\-\s*|\s+)(\S[\s\S]*))?\s*$/; 4 | 5 | /** 6 | * Extract the name information from a tag 7 | * @param {Tag} tag The tag to process 8 | */ 9 | module.exports = function extractNameTransform() { 10 | return function(doc, tag, value) { 11 | 12 | tag.description = value.replace(NAME_AND_DESCRIPTION, function(match, name, optionalName, defaultValue, description, dashDescription) { 13 | tag.name = optionalName || name; 14 | 15 | if ( optionalName ) { 16 | tag.optional = true; 17 | } 18 | 19 | if ( defaultValue ) { 20 | tag.defaultValue = defaultValue; 21 | } 22 | 23 | var aliasParts = tag.name.split('|'); 24 | tag.name = aliasParts[0]; 25 | tag.alias = aliasParts[1]; 26 | return dashDescription || description || ''; 27 | }); 28 | 29 | return tag.description; 30 | 31 | }; 32 | }; -------------------------------------------------------------------------------- /ngdoc/processors/filterNgdocs.spec.js: -------------------------------------------------------------------------------- 1 | var mockPackage = require('../mocks/mockPackage'); 2 | var Dgeni = require('dgeni'); 3 | 4 | function createMockTagCollection(tags) { 5 | return { 6 | getTag: function(value) { 7 | return tags[value]; 8 | } 9 | }; 10 | } 11 | 12 | 13 | describe("filter-ngdocs doc-processor plugin", function() { 14 | var processor; 15 | 16 | beforeEach(function() { 17 | var dgeni = new Dgeni([mockPackage()]); 18 | var injector = dgeni.configureInjector(); 19 | processor = injector.get('filterNgDocsProcessor'); 20 | }); 21 | 22 | it("should only return docs that have the ngdoc tag", function() { 23 | 24 | var doc1 = { tags: createMockTagCollection({ngdoc: 'a'}) }; 25 | 26 | var doc2 = { tags: createMockTagCollection({other: 'b'}) }; 27 | 28 | var doc3 = { tags: createMockTagCollection({ngdoc: 'c', other: 'd'}) }; 29 | 30 | var doc4 = { tags: createMockTagCollection({}) }; 31 | 32 | var docs = [ doc1, doc2, doc3, doc4 ]; 33 | 34 | var filteredDocs = processor.$process(docs); 35 | 36 | expect(filteredDocs).toEqual([doc1, doc3]); 37 | }); 38 | }); -------------------------------------------------------------------------------- /base/processors/debugDumpProcessor.js: -------------------------------------------------------------------------------- 1 | var path = require('canonical-path'); 2 | var util = require("util"); 3 | 4 | /** 5 | * @dgProcessor debugDumpProcessor 6 | * @description 7 | * This processor dumps docs that match a filter to a file 8 | */ 9 | module.exports = function debugDumpProcessor(log, readFilesProcessor, writeFile) { 10 | return { 11 | filterFn: function(docs) { return docs; }, 12 | outputPath: 'debug-dump.txt', 13 | depth: 2, 14 | 15 | $enabled: false, 16 | 17 | $validate: { 18 | filterFn: { presence: true }, 19 | outputPath: { presence: true }, 20 | depth: { presence: true } 21 | }, 22 | 23 | $runBefore: ['writing-files'], 24 | 25 | $process: function(docs) { 26 | log.info('Dumping docs:', this.filterFn, this.outputPath); 27 | var filteredDocs = this.filterFn(docs); 28 | var dumpedDocs = util.inspect(filteredDocs, this.depth); 29 | var outputPath = path.resolve(readFilesProcessor.basePath, this.outputPath); 30 | return writeFile(outputPath, dumpedDocs).then(function() { 31 | return docs; 32 | }); 33 | } 34 | }; 35 | 36 | }; -------------------------------------------------------------------------------- /ngdoc/services/getDocFromAlias.js: -------------------------------------------------------------------------------- 1 | var _ = require('lodash'); 2 | 3 | /** 4 | * @dgService getDocFromAlias 5 | * @description Get an array of docs that match this alias, relative to the originating doc. 6 | */ 7 | module.exports = function getDocFromAlias(aliasMap, log) { 8 | 9 | return function getDocFromAlias(alias, originatingDoc) { 10 | var docs = aliasMap.getDocs(alias); 11 | 12 | // If there is more than one item with this name then try to filter them by the originatingDoc's area 13 | if ( docs.length > 1 && originatingDoc && originatingDoc.area) { 14 | docs = _.filter(docs, function(doc) { 15 | return doc.area === originatingDoc.area; 16 | }); 17 | } 18 | 19 | // If filtering by area left us with none then let's start again 20 | if ( docs.length === 0 ) { 21 | docs = aliasMap.getDocs(alias); 22 | } 23 | 24 | // If there is more than one item with this name then try to filter them by the originatingDoc's module 25 | if ( docs.length > 1 && originatingDoc && originatingDoc.module ) { 26 | docs = _.filter(docs, function(doc) { 27 | return doc.module === originatingDoc.module; 28 | }); 29 | } 30 | 31 | return docs; 32 | }; 33 | }; -------------------------------------------------------------------------------- /nunjucks/services/nunjucks-template-engine.js: -------------------------------------------------------------------------------- 1 | var nunjucks = require('nunjucks'); 2 | 3 | /** 4 | * @dgService templateEngine 5 | * @description A nunjucks powered template rendering engine 6 | */ 7 | module.exports = function templateEngine(templateFinder) { 8 | 9 | return { 10 | 11 | /** 12 | * Nunjucks specific options, such as using `{$ $}` for nunjucks interpolation 13 | * rather than `{{ }}`, which conflicts with AngularJS 14 | */ 15 | config: {}, 16 | 17 | filters: [], 18 | tags: [], 19 | 20 | getRenderer: function() { 21 | var loader = new nunjucks.FileSystemLoader(templateFinder.templateFolders, true); 22 | var engine = new nunjucks.Environment(loader, this.config); 23 | 24 | // Configure nunjucks with the custom filters 25 | this.filters.forEach(function(filter) { 26 | engine.addFilter(filter.name, filter.process); 27 | }); 28 | 29 | // Configure nunjucks with the custom tags 30 | this.tags.forEach(function(tag) { 31 | engine.addExtension(tag.tags[0], tag); 32 | }); 33 | 34 | return function render(template, data) { 35 | return engine.render(template, data); 36 | }; 37 | } 38 | }; 39 | }; -------------------------------------------------------------------------------- /base/services/extractLinks.spec.js: -------------------------------------------------------------------------------- 1 | var mockPackage = require('../mocks/mockPackage'); 2 | var Dgeni = require('dgeni'); 3 | 4 | describe("extractLinks", function() { 5 | var urlExtractor; 6 | 7 | beforeEach(function() { 8 | var dgeni = new Dgeni([mockPackage()]); 9 | var injector = dgeni.configureInjector(); 10 | extractLinks = injector.get('extractLinks'); 11 | }); 12 | 13 | it("should extract the hrefs from anchors", function() { 14 | expect(extractLinks('bar').hrefs).toEqual(['foo']); 15 | expect(extractLinks('barshell').hrefs).toEqual(['foo', 'man']); 16 | expect(extractLinks('
some paragraph
\n' + 31 | 'code\n' +
35 | ' indented code\n' +
36 | 'code\n' +
37 | 'abc<div>&</div><div> </div>abc');
28 | });
29 | });
30 |
31 | describe("language", function() {
32 | it("should add a CSS class if a language is specified", function() {
33 | expect(encodeCodeBlock('abc', true, 'js')).toEqual('abc');
34 | });
35 | });
36 | });
--------------------------------------------------------------------------------
/ngdoc/file-readers/ngdoc.spec.js:
--------------------------------------------------------------------------------
1 | var ngdocFileReaderFactory = require('./ngdoc');
2 | var path = require('canonical-path');
3 |
4 | describe("ngdocFileReader", function() {
5 |
6 | var fileReader;
7 |
8 | var createFileInfo = function(file, content, basePath) {
9 | return {
10 | fileReader: fileReader.name,
11 | filePath: file,
12 | baseName: path.basename(file, path.extname(file)),
13 | extension: path.extname(file).replace(/^\./, ''),
14 | basePath: basePath,
15 | relativePath: path.relative(basePath, file),
16 | content: content
17 | };
18 | };
19 |
20 |
21 | beforeEach(function() {
22 | fileReader = ngdocFileReaderFactory();
23 | });
24 |
25 |
26 | describe("defaultPattern", function() {
27 | it("should match .ngdoc files", function() {
28 | expect(fileReader.defaultPattern.test('abc.ngdoc')).toBeTruthy();
29 | expect(fileReader.defaultPattern.test('abc.js')).toBeFalsy();
30 | });
31 | });
32 |
33 |
34 | describe("getDocs", function() {
35 | it('should return an object containing info about the file and its contents', function() {
36 | var fileInfo = createFileInfo('foo/bar.ngdoc', 'A load of content', 'base/path');
37 | expect(fileReader.getDocs(fileInfo)).toEqual([{
38 | content: 'A load of content',
39 | startingLine: 1
40 | }]);
41 | });
42 | });
43 | });
44 |
45 |
--------------------------------------------------------------------------------
/ngdoc/tag-defs/module.spec.js:
--------------------------------------------------------------------------------
1 | var path = require('canonical-path');
2 | var tagDefFactory = require('./module');
3 |
4 | describe("module tag-def", function() {
5 | it("should calculate the module from the second segment of the file path", function() {
6 | var tagDef = tagDefFactory();
7 | expect(tagDef.defaultFn({ area: 'api', fileInfo: { relativePath: 'ng/service/$http.js' } })).toEqual('ng');
8 | });
9 |
10 | it("should use the relative file path", function() {
11 | var tagDef = tagDefFactory();
12 | var relativePath = 'ng/service/$http.js';
13 | expect(tagDef.defaultFn({ area: 'api', fileInfo: { filePath: path.resolve(relativePath), relativePath: relativePath } })).toEqual('ng');
14 | });
15 |
16 | it("should not calculate module if the doc is not in 'api' area", function() {
17 | var tagDef = tagDefFactory();
18 | var relativePath = 'guide/concepts.ngdoc';
19 | expect(tagDef.defaultFn({ area: 'guide', fileInfo: { filePath: path.resolve(relativePath), relativePath: relativePath } })).toBeUndefined();
20 | });
21 |
22 | it("should not calculate module if the doc has docType 'overview'", function() {
23 | var tagDef = tagDefFactory();
24 | var relativePath = 'api/index.ngdoc';
25 | expect(tagDef.defaultFn({ docType: 'overview', area: 'api', fileInfo: { filePath: path.resolve(relativePath), relativePath: relativePath } })).toBeUndefined();
26 | });
27 | });
--------------------------------------------------------------------------------
/ngdoc/processors/providerDocs.js:
--------------------------------------------------------------------------------
1 | var _ = require('lodash');
2 |
3 | /**
4 | * @dgProcessor providerDocsProcessor
5 | * @description
6 | * Connect docs for services to docs for their providers
7 | */
8 | module.exports = function providerDocsProcessor(log, aliasMap, createDocMessage) {
9 | return {
10 | $runAfter: ['ids-computed', 'memberDocsProcessor'],
11 | $runBefore: ['computing-paths'],
12 | $process: function(docs) {
13 |
14 | // Map services to their providers
15 | _.forEach(docs, function(doc) {
16 | if ( doc.docType === 'provider' ) {
17 | var serviceId = doc.id.replace(/provider:/, 'service:').replace(/Provider$/, '');
18 | var serviceDocs = aliasMap.getDocs(serviceId);
19 |
20 | if ( serviceDocs.length === 1 ) {
21 | serviceDoc = serviceDocs[0];
22 | doc.serviceDoc = serviceDoc;
23 | serviceDoc.providerDoc = doc;
24 | } else if ( serviceDocs.length === 0 ) {
25 | log.warn(createDocMessage('Missing service "' + serviceId + '" for provider', doc));
26 | } else {
27 | log.warn(createDocMessage('Ambiguous service name "' + serviceId + '" for provider', doc) + '\n' +
28 | _.reduce(serviceDocs, function(msg, doc) {
29 | return msg + '\n "' + doc.id + '"';
30 | }, 'Matching docs: '));
31 | }
32 | }
33 | });
34 | }
35 | };
36 | };
--------------------------------------------------------------------------------
/nunjucks/services/renderMarkdown.spec.js:
--------------------------------------------------------------------------------
1 | var Dgeni = require('dgeni');
2 | var mockPackage = require('../mocks/mockPackage');
3 |
4 | describe("renderMarkdown", function() {
5 |
6 | var renderMarkdown, trimIndentation;
7 |
8 | beforeEach(function() {
9 | var dgeni = new Dgeni([mockPackage()]);
10 | var injector = dgeni.configureInjector();
11 | trimIndentation = injector.get('trimIndentation');
12 | renderMarkdown = injector.get('renderMarkdown');
13 | });
14 |
15 | it("should render the given markdown content as HTML", function() {
16 | var html = renderMarkdown(
17 | '## heading 2\n\n' +
18 | 'some paragraph\n\n' +
19 | '* a bullet point');
20 | expect(html).toEqual(
21 | 'some paragraph
\n' + 23 | 'some test
\n' + 41 | 'code\n' +
42 | ' indented code\n' +
43 | 'more code\n' +
44 | 'more text
\n' 46 | ); 47 | 48 | }); 49 | 50 | }); -------------------------------------------------------------------------------- /ngdoc/processors/generateComponentGroups.js: -------------------------------------------------------------------------------- 1 | var _ = require('lodash'); 2 | 3 | /** 4 | * @dgProcessor generateComponentGroupsProcessor 5 | * @description 6 | * Generate documents for each group of components (by type) within a module 7 | */ 8 | module.exports = function generateComponentGroupsProcessor(moduleMap) { 9 | return { 10 | $runAfter: ['moduleDocsProcessor'], 11 | $runBefore: ['computing-paths'], 12 | $process: function(docs) { 13 | 14 | moduleMap.forEach(function(module) { 15 | 16 | _(module.components) 17 | .groupBy('docType') 18 | .tap(function(docTypes) { 19 | // We don't want the overview docType to be represented as a componentGroup 20 | delete docTypes.overview; 21 | }) 22 | .map(function(docs, docType) { 23 | return { 24 | id: module.id + '.' + docType, 25 | docType: 'componentGroup', 26 | groupType: docType, 27 | moduleName: module.name, 28 | moduleDoc: module, 29 | area: module.area, 30 | name: docType + ' components in ' + module.name, 31 | components: docs 32 | }; 33 | }) 34 | .tap(function(groups) { 35 | module.componentGroups = groups; 36 | _.forEach(groups, function(group) { 37 | docs.push(group); 38 | }); 39 | }); 40 | }); 41 | } 42 | }; 43 | }; -------------------------------------------------------------------------------- /base/processors/write-files.js: -------------------------------------------------------------------------------- 1 | var _ = require('lodash'); 2 | var path = require('canonical-path'); 3 | var fs = require('q-io/fs'); 4 | var Q = require('q'); 5 | 6 | /** 7 | * @dgProcessor writeFilesProcessor 8 | * @param {Object} log A service that provides logging 9 | * @description Write the value of `doc.renderedContent` to a file a `doc.outputPath`. 10 | * @property {String} outputFolder The base path to the folder where files are outputted 11 | */ 12 | module.exports = function writeFilesProcessor(log, readFilesProcessor, writeFile) { 13 | return { 14 | outputFolder: null, 15 | $validate: { 16 | outputFolder: { presence: true }, 17 | }, 18 | $runAfter:['writing-files'], 19 | $runBefore: ['files-written'], 20 | $process: function(docs) { 21 | var outputFolder = this.outputFolder; 22 | return Q.all(_.map(docs, function(doc) { 23 | 24 | if ( !doc.outputPath ) { 25 | log.debug('Document "' + doc.id + ', ' + doc.docType + '" has no outputPath.'); 26 | } else { 27 | 28 | var outputFile = path.resolve(readFilesProcessor.basePath, outputFolder, doc.outputPath); 29 | 30 | log.silly('writing file', outputFile); 31 | return writeFile(outputFile, doc.renderedContent).then(function() { 32 | log.debug('written file', outputFile); 33 | return outputFile; 34 | }); 35 | 36 | } 37 | })).then(function() { 38 | return docs; 39 | }); 40 | } 41 | }; 42 | }; -------------------------------------------------------------------------------- /base/processors/write-files.spec.js: -------------------------------------------------------------------------------- 1 | var path = require('canonical-path'); 2 | var Q = require('q'); 3 | 4 | var mockPackage = require('../mocks/mockPackage'); 5 | var Dgeni = require('dgeni'); 6 | 7 | describe("writeFilesProcessor", function() { 8 | var processor, writeFileSpy, mockLog; 9 | 10 | 11 | beforeEach(function() { 12 | writeFileSpy = jasmine.createSpy('writeFile').and.returnValue(Q()); 13 | 14 | var testPackage = mockPackage().factory('writeFile', function() { return writeFileSpy; }); 15 | 16 | var dgeni = new Dgeni([testPackage]); 17 | var injector = dgeni.configureInjector(); 18 | 19 | var readFilesProcessor = injector.get('readFilesProcessor'); 20 | readFilesProcessor.basePath = path.resolve('some/path'); 21 | 22 | processor = injector.get('writeFilesProcessor'); 23 | processor.outputFolder = 'build'; 24 | 25 | mockLog = injector.get('log'); 26 | }); 27 | 28 | it("should write each document to a file", function() { 29 | processor.$process([{ renderedContent: 'SOME RENDERED CONTENT', outputPath: 'doc/path.html' }]); 30 | expect(writeFileSpy).toHaveBeenCalledWith(path.resolve('some/path/build/doc/path.html'), 'SOME RENDERED CONTENT'); 31 | }); 32 | 33 | it("should log a debug message if a doc has no outputPath", function() { 34 | processor.$process([{ renderedContent: 'SOME RENDERED CONTENT', id: 'doc1', docType: 'test' }]); 35 | expect(mockLog.debug).toHaveBeenCalledWith('Document "doc1, test" has no outputPath.'); 36 | }); 37 | }); -------------------------------------------------------------------------------- /ngdoc/tag-defs/restrict.spec.js: -------------------------------------------------------------------------------- 1 | var tagDefFactory = require('./restrict'); 2 | 3 | describe("restrict tag-def", function() { 4 | var tagDef; 5 | 6 | beforeEach(function() { 7 | tagDef = tagDefFactory(); 8 | }); 9 | 10 | it("should convert a restrict tag text to an object", function() { 11 | expect(tagDef.transforms({}, {}, 'A')).toEqual({ element: false, attribute: true, cssClass: false, comment: false }); 12 | expect(tagDef.transforms({}, {}, 'C')).toEqual({ element: false, attribute: false, cssClass: true, comment: false }); 13 | expect(tagDef.transforms({}, {}, 'E')).toEqual({ element: true, attribute: false, cssClass: false, comment: false }); 14 | expect(tagDef.transforms({}, {}, 'M')).toEqual({ element: false, attribute: false, cssClass: false, comment: true }); 15 | expect(tagDef.transforms({}, {}, 'ACEM')).toEqual({ element: true, attribute: true, cssClass: true, comment: true }); 16 | }); 17 | 18 | it("should default to restricting to an attribute if no tag is found and the doc is for a directive", function() { 19 | expect(tagDef.defaultFn({ docType: 'directive' })).toEqual({ element: false, attribute: true, cssClass: false, comment: false }); 20 | expect(tagDef.defaultFn({ docType: 'input' })).toEqual({ element: false, attribute: true, cssClass: false, comment: false }); 21 | }); 22 | 23 | it("should not add a restrict property if the docType is not 'directive'", function() { 24 | expect(tagDef.defaultFn({ docType: 'service' })).toBeUndefined(); 25 | }); 26 | }); 27 | 28 | -------------------------------------------------------------------------------- /examples/processors/protractor-generate.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | var _ = require('lodash'); 4 | 5 | /** 6 | * dgProcessor generateProtractorTestsProcessor 7 | * @description 8 | * Generate a protractor test files from the e2e tests in the examples 9 | */ 10 | module.exports = function generateProtractorTestsProcessor(exampleMap) { 11 | return { 12 | deployments: [], 13 | basePath: '', 14 | $validate: { 15 | deployments: { presence: true }, 16 | }, 17 | $runAfter: ['adding-extra-docs'], 18 | $runBefore: ['extra-docs-added'], 19 | $process: function(docs) { 20 | 21 | var deployments = this.deployments; 22 | var basePath = this.basePath; 23 | 24 | exampleMap.forEach(function(example) { 25 | _.forEach(example.files, function(file) { 26 | 27 | // Check if it's a Protractor test. 28 | if (file.type === 'protractor') { 29 | 30 | _.forEach(deployments, function(deployment) { 31 | docs.push(createProtractorDoc(example, deployment, file, basePath)); 32 | }); 33 | } 34 | 35 | }); 36 | }); 37 | } 38 | }; 39 | }; 40 | 41 | function createProtractorDoc(example, deployment, file, basePath) { 42 | return { 43 | docType: 'e2e-test', 44 | id: 'protractorTest' + '-' + example.id + '-' + deployment.name, 45 | example: example, 46 | deployment: deployment, 47 | template: 'protractorTests.template.js', 48 | innerTest: file.fileContents, 49 | 'ng-app-included': example['ng-app-included'], 50 | basePath: basePath 51 | }; 52 | } -------------------------------------------------------------------------------- /jsdoc/services/transforms/extract-name.spec.js: -------------------------------------------------------------------------------- 1 | var transformFactory = require('./extract-name'); 2 | 3 | describe("extract-name transform", function() { 4 | var doc, tag, value, transform; 5 | 6 | beforeEach(function() { 7 | doc = {}; 8 | tag = {}; 9 | transform = transformFactory(); 10 | }); 11 | 12 | it("should extract the name from the description", function() { 13 | 14 | value = ' paramName - Some description \n Some more description'; 15 | value = transform(doc, tag, value); 16 | 17 | expect(tag.name).toEqual('paramName'); 18 | expect(value).toEqual('Some description \n Some more description'); 19 | }); 20 | 21 | it("should extract an optional name", function() { 22 | value = '[someName]'; 23 | value = transform(doc, tag, value); 24 | expect(tag.name).toEqual('someName'); 25 | expect(tag.optional).toEqual(true); 26 | expect(value).toEqual(''); 27 | }); 28 | 29 | it("should extract a name and its default value", function() { 30 | value = '[someName=someDefault]'; 31 | value = transform(doc, tag, value); 32 | expect(tag.name).toEqual('someName'); 33 | expect(tag.optional).toEqual(true); 34 | expect(tag.defaultValue).toEqual('someDefault'); 35 | expect(value).toEqual(''); 36 | }); 37 | 38 | it("should extract a param name alias", function() { 39 | value = 'paramName|aliasName some description'; 40 | value = transform(doc, tag, value); 41 | expect(tag.name).toEqual('paramName'); 42 | expect(tag.alias).toEqual('aliasName'); 43 | expect(value).toEqual('some description'); 44 | }); 45 | 46 | }); -------------------------------------------------------------------------------- /examples/index.js: -------------------------------------------------------------------------------- 1 | var path = require('canonical-path'); 2 | var packagePath = __dirname; 3 | var Package = require('dgeni').Package; 4 | 5 | module.exports = new Package('examples', ['jsdoc']) 6 | 7 | .processor(require('./processors/examples-parse')) 8 | .processor(require('./processors/examples-generate')) 9 | .processor(require('./processors/protractor-generate')) 10 | 11 | .factory(require('./services/exampleMap')) 12 | .factory(require('./inline-tag-defs/runnableExample')) 13 | 14 | .config(function(templateFinder, generateExamplesProcessor) { 15 | templateFinder.templateFolders.push(path.resolve(packagePath, 'templates')); 16 | 17 | }) 18 | 19 | .config(function(inlineTagProcessor, runnableExampleInlineTagDef) { 20 | inlineTagProcessor.inlineTagDefinitions.push(runnableExampleInlineTagDef); 21 | }) 22 | 23 | .config(function(computePathsProcessor, computeIdsProcessor) { 24 | computePathsProcessor.pathTemplates.push({ 25 | docTypes: ['example'], 26 | pathTemplate: 'examples/${example.id}', 27 | outputPathTemplate: 'examples/${example.id}/index${deploymentQualifier}.html' 28 | }); 29 | computePathsProcessor.pathTemplates.push({ 30 | docTypes: ['example-file'], 31 | getPath: function() {}, 32 | outputPathTemplate: 'examples/${id}' 33 | }); 34 | computePathsProcessor.pathTemplates.push({ 35 | docTypes: ['runnableExample' ], 36 | pathTemplate: 'examples/${example.id}', 37 | getOutputPath: function() {}, 38 | }); 39 | 40 | computeIdsProcessor.idTemplates.push({ 41 | docTypes: ['example', 'example-file', 'runnableExample'], 42 | getAliases: function(doc) { return [doc.id]; } 43 | }); 44 | }); -------------------------------------------------------------------------------- /jsdoc/tag-defs/memberof.spec.js: -------------------------------------------------------------------------------- 1 | var mockPackage = require('../mocks/mockPackage'); 2 | var Dgeni = require('dgeni'); 3 | var tagDefFactory = require('./memberof'); 4 | 5 | describe("memberof tag-def", function() { 6 | var tagDef; 7 | 8 | beforeEach(function() { 9 | var dgeni = new Dgeni([mockPackage()]); 10 | var injector = dgeni.configureInjector(); 11 | tagDef = injector.invoke(tagDefFactory); 12 | }); 13 | 14 | describe('transforms', function() { 15 | it("should throw an exception if the docType is not 'event', 'method' or 'property'", function() { 16 | expect(function() { 17 | tagDef.transforms({ docType: 'unknown'}); 18 | }).toThrowError(); 19 | 20 | expect(function() { 21 | tagDef.transforms({ docType: 'event'}); 22 | }).not.toThrowError(); 23 | 24 | expect(function() { 25 | tagDef.transforms({ docType: 'method'}); 26 | }).not.toThrowError(); 27 | 28 | expect(function() { 29 | tagDef.transforms({ docType: 'property'}); 30 | }).not.toThrowError(); 31 | }); 32 | }); 33 | 34 | 35 | describe("defaultFn", function() { 36 | it("should throw an exception if the docType is 'event', 'method' or 'property'", function() { 37 | expect(function() { 38 | tagDef.defaultFn({ docType: 'unknown'}); 39 | }).not.toThrowError(); 40 | 41 | expect(function() { 42 | tagDef.defaultFn({ docType: 'event'}); 43 | }).toThrowError(); 44 | 45 | expect(function() { 46 | tagDef.defaultFn({ docType: 'method'}); 47 | }).toThrowError(); 48 | 49 | expect(function() { 50 | tagDef.defaultFn({ docType: 'property'}); 51 | }).toThrowError(); 52 | }); 53 | }); 54 | }); -------------------------------------------------------------------------------- /ngdoc/templates/api/api.template.html: -------------------------------------------------------------------------------- 1 | {% extends "base.template.html" %} 2 | 3 | {% block content %} 4 | 5 | 6 | View Source 7 | 8 | 9 | {% block header %} 10 || Param | 10 |Type | 11 |Details | 12 |
|---|---|---|
|
18 | {$ param.name $}
19 | {% if param.alias %}| {$ param.alias $}{% endif %}
20 | {% if param.type.optional %} (optional) {% endif %}
21 | |
22 | 23 | {$ typeList(param.typeList) $} 24 | | 25 |
26 | {$ param.description | marked $}
27 | {% if param.defaultValue %} (default: {$ param.defaultValue $}) {% endif %} 28 | |
29 |
| {$ typeList(fn.typeList) $} | 57 |{$ fn.description | marked $} | 58 |
some paragraph
\n' + 29 | 'First include {$ doc.packageFile | code $} in your HTML:
14 | 15 | {% code %} 16 |