fix issues with doclet names that are filepaths (#590)

Prior to this fix, if a file was outside of the JSDoc
directory, and your code included something like a
`@file` tag, we would set the doclet's name to the
entire filepath instead of the shortened filepath.

With this fix, we set the name to the shortened
filepath.

lib/jsdoc/tag/dictionary/definitions.js

@@ -12,9 +12,24 @@ var logger = require('jsdoc/util/logger');
 var path = require('jsdoc/path');
 var Syntax = require('jsdoc/src/syntax').Syntax;
 
+function getSourcePaths() {
+    var sourcePaths = env.sourceFiles.slice(0) || [];
+
+    if (env.opts._) {
+        env.opts._.forEach(function(sourcePath) {
+            var resolved = path.resolve(env.pwd, sourcePath);
+            if (sourcePaths.indexOf(resolved) === -1) {
+                sourcePaths.push(resolved);
+            }
+        });
+    }
+
+    return sourcePaths;
+}
+
 function filepathMinusPrefix(filepath) {
-    var sourceFiles = env.sourceFiles || [];
-    var commonPrefix = path.commonPrefix( sourceFiles.concat(env.opts._ || []) );
+    var sourcePaths = getSourcePaths();
+    var commonPrefix = path.commonPrefix(sourcePaths);
     var result = '';
 
     if (filepath) {

test/specs/tags/overviewtag.js

@@ -1,5 +1,4 @@
-/*global beforeEach: true, afterEach: true, describe: true, env: true, expect: true, it: true,
-jasmine: true */
+/*global beforeEach, afterEach, describe, env, expect, it, jasmine */
 
 describe("@overview tag", function() {
     var path = require('jsdoc/path');
@@ -45,4 +44,31 @@ describe("@overview tag", function() {
         );
         expect(doclets[0].name).toBe(doclets[0].longname);
     });
+
+    it('The name should not include the entire filepath when the source file is outside the ' +
+        'JSDoc directory', function() {
+        var Doclet = require('jsdoc/doclet').Doclet;
+
+        var doclet;
+        var docletMeta;
+        var docletSrc;
+
+        var fakePath = '/Users/jdoe/foo/bar/someproject/junk/okayfile.js';
+
+        // set up the environment to reflect the fake filepath
+        env.pwd = '/Users/jdoe/someproject';
+        env.sourceFiles = [];
+        env.opts._ = [fakePath];
+
+        // create a doclet with a fake filepath, then add a `@file` tag
+        docletSrc = '/** @class */';
+        docletMeta = {
+            lineno: 1,
+            filename: fakePath
+        };
+        doclet = new Doclet(docletSrc, docletMeta);
+        doclet.addTag('file', 'This file is pretty okay.');
+
+        expect(doclet.name).toBe('okayfile.js');
+    });
 });