diff --git a/lib/mocha.js b/lib/mocha.js
index cfdec4b90e..144b19e335 100644
--- a/lib/mocha.js
+++ b/lib/mocha.js
@@ -156,7 +156,7 @@ Mocha.prototype.bail = function(bail) {
* Useful for generic setup code that must be included within test suite.
*
* @public
- * @see {@link /#-file-filedirectoryglob|CLI option}
+ * @see [CLI option](../#-file-filedirectoryglob)
* @param {string} file - Pathname of file to be loaded.
* @returns {Mocha} this
* @chainable
@@ -170,8 +170,8 @@ Mocha.prototype.addFile = function(file) {
* Sets reporter to `reporter`, defaults to "spec".
*
* @public
- * @see {@link /#-reporter-name-r-name|CLI option}
- * @see {@link /#reporters|Reporters}
+ * @see [CLI option](../#-reporter-name-r-name)
+ * @see [Reporters](../#reporters)
* @param {String|Function} reporter - Reporter name or constructor.
* @param {Object} [reporterOptions] - Options used to configure the reporter.
* @returns {Mocha} this
@@ -239,8 +239,8 @@ Mocha.prototype.reporter = function(reporter, reporterOptions) {
* Sets test UI `name`, defaults to "bdd".
*
* @public
- * @see {@link /#-ui-name-u-name|CLI option}
- * @see {@link /#interfaces|Interface DSLs}
+ * @see [CLI option](../#-ui-name-u-name)
+ * @see [Interface DSLs](../#interfaces)
* @param {string|Function} [ui=bdd] - Interface name or class.
* @returns {Mocha} this
* @chainable
@@ -332,9 +332,7 @@ Mocha.unloadFile = function(file) {
*
* Intended for consumers — not used internally
*
- * @public
- * @see {@link Mocha.unloadFile}
- * @see {@link Mocha#loadFiles}
+ * @publicoption
* @see {@link Mocha#run}
* @returns {Mocha} this
* @chainable
@@ -378,7 +376,7 @@ Mocha.prototype.fgrep = function(str) {
* Previous filter value will be overwritten on each call!
*
* @public
- * @see {@link /#grep-regexp-g-regexp|CLI option}
+ * @see [CLI option](../#-grep-regexp-g-regexp)
* @see {@link Mocha#fgrep}
* @see {@link Mocha#invert}
* @param {RegExp|String} re - Regular expression used to select tests.
@@ -476,8 +474,7 @@ Mocha.prototype.fullTrace = function(fullTrace) {
* Enables desktop notification support if prerequisite software installed.
*
* @public
- * @see {@link Mocha#isGrowlCapable}
- * @see {@link Mocha#_growl}
+ * @see [CLI option](../#-growl-g)
* @return {Mocha} this
* @chainable
*/
@@ -647,8 +644,8 @@ Mocha.prototype.diff = function(diff) {
* If the value is `0`, timeouts will be disabled.
*
* @public
- * @see {@link /#-timeout-ms-t-ms|CLI option}
- * @see {@link /#timeouts|Timeouts}
+ * @see [CLI option](../#-timeout-ms-t-ms)
+ * @see [Timeouts](../#timeouts)
* @see {@link Mocha#enableTimeouts}
* @param {number|string} msecs - Timeout threshold value.
* @return {Mocha} this
@@ -671,7 +668,8 @@ Mocha.prototype.timeout = function(msecs) {
* Sets the number of times to retry failed tests.
*
* @public
- * @see {@link /#retry-tests|Retry Tests}
+ * @see [CLI option](../#-retries-n)
+ * @see [Retry Tests](../#retry-tests)
* @param {number} retry - Number of times to retry failed tests.
* @return {Mocha} this
* @chainable
@@ -689,7 +687,7 @@ Mocha.prototype.retries = function(n) {
* Sets slowness threshold value.
*
* @public
- * @see {@link /#-slow-ms-s-ms|CLI option}
+ * @see [CLI option](../#-slow-ms-s-ms)
* @param {number} msecs - Slowness threshold value.
* @return {Mocha} this
* @chainable
@@ -711,7 +709,7 @@ Mocha.prototype.slow = function(msecs) {
* Enables or disables timeouts.
*
* @public
- * @see {@link /#-timeout-ms-t-ms|CLI option}
+ * @see [CLI option](../#-timeout-ms-t-ms)
* @param {boolean} enableTimeouts - Whether to enable timeouts.
* @return {Mocha} this
* @chainable
@@ -771,7 +769,7 @@ Mocha.prototype.allowUncaught = function(allowUncaught) {
* Used to perform asynch operations before any suites are run.
*
* @public
- * @see {@link /#delayed-root-suite|delayed root suite}
+ * @see [delayed root suite](../#delayed-root-suite)
* @returns {Mocha} this
* @chainable
*/
@@ -838,7 +836,6 @@ Object.defineProperty(Mocha.prototype, 'version', {
* the cache first!
*
* @public
- * @see {@link Mocha#loadFiles}
* @see {@link Mocha#unloadFiles}
* @see {@link Runner#run}
* @param {DoneCB} [fn] - Callback invoked when test execution completed.