JavaScript函数控制台可访问注释：对标MATLAB help功能

Great question! In JavaScript, we don’t have a built-in help() command like MATLAB, but we’ve got a couple of straightforward ways to add accessible, human-readable documentation to functions that you can check right in the console. Let’s break them down:

1. JSDoc: The Industry-Standard Documentation Format #

JSDoc is the de facto standard for documenting JavaScript code. It uses special comment blocks that most modern development tools (including browser dev tools and IDEs) can parse and display.

Here’s how to write a JSDoc comment for a function:

/**
 * Calculates the area of a rectangle.
 * @param {number} width - The width of the rectangle (must be a positive number).
 * @param {number} height - The height of the rectangle (must be a positive number).
 * @returns {number} The computed area of the rectangle.
 * @throws {Error} If either width or height is non-positive.
 */
function calculateRectangleArea(width, height) {
  if (width <= 0 || height <= 0) {
    throw new Error("Width and height must be positive numbers.");
  }
  return width * height;
}

How to view it in the console: #

• In Chrome DevTools (or similar browsers), type calculateRectangleArea and press Enter. Hover over the function result, or expand the [[FunctionLocation]] link to see the full JSDoc comment in the Sources panel.
• If you want to directly print the comment to the console, you can extract it from the function’s string representation:

  console.log(calculateRectangleArea.toString().match(/\/\*\*([\s\S]*?)\*\//)[1].trim());
  

2. Custom help Property/Method: Mimic MATLAB’s help Command #

If you want a more direct, MATLAB-like experience, you can add a custom help property or method to your function. This lets users call something like myFunction.help or myFunction.showHelp() to see documentation instantly.

Example with a help property:

function calculateRectangleArea(width, height) {
  if (width <= 0 || height <= 0) {
    throw new Error("Width and height must be positive numbers.");
  }
  return width * height;
}

// Add a readable help string as a property
calculateRectangleArea.help = `
Calculates the area of a rectangle.
Parameters:
- width (number): Positive number representing the rectangle's width.
- height (number): Positive number representing the rectangle's height.
Returns:
- number: The total area of the rectangle.
Throws:
- Error: If either parameter is zero or negative.
`;

Now in the console, just type calculateRectangleArea.help and press Enter to see the full documentation. For a cleaner output, add a showHelp method:

calculateRectangleArea.showHelp = function() {
  console.log(this.help);
};

// Usage in console:
// calculateRectangleArea.showHelp();

3. Reusable Wrapper for Multiple Functions #

If you have lots of functions to document, a wrapper function can save you from repeating code. This lets you attach documentation to any function in one step:

function withDocumentation(fn, documentation) {
  // Attach the help string
  fn.help = documentation;
  // Add a method to log it
  fn.showHelp = () => console.log(documentation);
  return fn;
}

// Use the wrapper to create a documented function
const calculateCircleArea = withDocumentation(
  function(radius) {
    if (radius <= 0) throw new Error("Radius must be a positive number.");
    return Math.PI * radius ** 2;
  },
  `
Calculates the area of a circle.
Parameters:
- radius (number): Positive number representing the circle's radius.
Returns:
- number: The total area of the circle.
Throws:
- Error: If radius is zero or negative.
  `
);

Now calculateCircleArea.showHelp() will log its documentation just like the previous example.

内容的提问来源于stack exchange，提问作者sc28