为什么有些函数会出现在 JSDoc 中而有些函数却没有？

Question

这个函数显示在 html 文件中。

/**
 * This function allows us to display a graph depending on the selection in a dropdown list
 * @param {object} object the div that is passed into the function
 */
/**
 * This function allows us to display a graph depending on the selection in a dropdown list
 * @param {object} object the div that is passed into the function
 */
function changeTitle(object) {
  /**
   * This retrieves the option clicked within the dropdown.
   */
  const dropdownChoice = document.getElementById('gdropdown').selectedIndex;
  /**
   * This collects the carousel meant to show if the heel height/UK economy line graph is selected.
   */
  const carousel = document.getElementById('yearscarousel');
  /**
   * This selects the caption that should be displayed alongside the carousel.
   */
  const carouselCaption = document.getElementById('linecaption');
  carousel.style.display = 'none';
  carouselCaption.style.display = 'none';
  if (dropdownChoice === 0) {
    document.getElementById('title').innerHTML = 'Scatter Graph that shows the skin colour of Vogue cover models';
    document.getElementById('scatgraph').innerHTML = '';
    /**
     * set the dimensions and margins of the graph
     */
    var margin = {
      top: 10, right: 30, bottom: 30, left: 60,
    };
    var width = 650 - margin.left - margin.right;
    var height = 450 - margin.top - margin.bottom;

    /**
     *  append the svg object to the body of the page
     */
    var svg = d3.select('#scatgraph')
      .append('svg')
      .attr('width', width + margin.left + margin.right)
      .attr('height', height + margin.top + margin.bottom)
      .append('g')
      .attr(
        'transform',
        `translate(${margin.left},${margin.top})`,
      );

    // Read the data
    d3.csv('faces.csv', (data) => {
      /**
       *  this creates the x axis of the scatter graph
       */
      const x = d3.scaleTime()
        .domain([new Date('01-01-2000'), new Date('01-01-2020')])
        .range([0, 500]);
      svg.append('g')
        .attr('transform', `translate(0,${height})`)
        .call(d3.axisBottom(x));

      /**
       * This adds the y axis of the scatter graph.
       */
      const y = d3.scaleLinear()
        .domain([0, 1])
        .range([height, 0]);
      svg.append('g')
        .call(d3.axisLeft(y));

      /**
       * Add a tooltip div. Here I define the general feature of the tooltip: stuff that do not depend on the data point.
       * Its opacity is set to 0: we don't see it by default.
       */
      const tooltip = d3.select('#scatgraph')
        .append('div')
        .style('opacity', 0)
        .attr('class', 'tooltip')
        .style('background-color', 'white')
        .style('border', 'solid')
        .style('border-width', '1px')
        .style('border-radius', '5px')

        .style('padding', '10px')
        .style('width', '20%');

      /**
       *
       * @param {Object} d
       */
      const mouseover = function (d) {
        tooltip
          .style('opacity', 1);
        console.log('Successful');
      };
      /**
       *
       * @param {Object} d
       */
      const mousemove = function (d) {
        tooltip
          .html(`Model name: ${d.model}`)
          .style('color', d.tone)
          .style('padding', '10px')
          .style('position', 'fixed')
          .style('left', `${d3.mouse(this)[0] + 50}px`) // It is important to put the +90: other wise the tooltip is exactly where the point is an it creates a weird effect
          .style('top', `${d3.mouse(this)[1]}px`);
        console.log('Successful');
      };

      /**
       * A function that change this tooltip when the leaves a point: just need to set opacity to 0 again
       * @param {Object} d
       */
      const mouseleave = function (d) {
        tooltip
          .transition()
          .duration(400)
          .style('opacity', 0);
        console.log('Succsessful');
      };

      // Add dots
      svg.append('g')
        .selectAll('dot')
        .data(data.filter((d, i) => i < 50)) // the .filter part is just to keep a few dots on the chart, not all of them
        .enter()
        .append('circle')
        .attr('cx', (d) => x(new Date(d.date)))
        .attr('cy', (d) => y(d.l))
        .attr('r', 7)
        .style('fill', '#c2044a')
        .style('opacity', 0.3)
        .style('stroke', 'white')
        .on('mouseover', mouseover)

        .on('mousemove', mousemove)
        .on('mouseleave', mouseleave);

      svg.append('text')
        .attr('class', 'x label')
        .attr('text-anchor', 'end')
        .attr('x', width - 20)
        .attr('y', height)
        .text('Year');

      svg.append('text')
        .attr('class', 'y label')
        .attr('text-anchor', 'end')
        .attr('y', 6)
        .attr('dy', '.75em')
        .attr('transform', 'rotate(-90)')
        .text('L Value for Skin Tone');

      console.log('Successful');
    });
  }
}

下面的代码在两个函数的中间。

console.log('The graphs should be working');
window.addEventListener('DOMContentLoaded', () => {
  console.log('DOM fully loaded and parsed');

但是这个功能没有出现，

/**
 * This function creates an alert box and resets value of the form
 * @param {event} click when the submit button is pressed
 */
function clickHandler(event) {
  alert('Thanks for your wonderful input.');
  document.getElementById('sleekform').reset();
  document.getElementById('sleektexta').value = '';
}
document.getElementById('submitB').addEventListener('click', clickHandler);
});

我运行 jsdoc 使用 'npm 安装 -g jsdoc' 然后 'jsdoc slimscript.js' 在终端中。

GARbkefhoijf4rpg4r g3r hoig43jofrosjlfdvjks; kfpojfspokrposjojrtsihsd 耶赫赛克夫斯 rwrwrrjvw;ihwihrw#fvwbwfo kjbvefjrjoerjuervbevbdv

Answer 1

更新答案

针对问题更新：

本地函数不是公共 API，不包含在 JSdoc 中。

来自How to document a nested function within a method in JSdoc

在 if/else 块和函数之外定义这些函数，然后 JSDoc 会看到它们。

（这就是为什么问题应该从一开始就包含一个真正的minimal reproducible example）

---

原答案

要记录传递给事件侦听器的函数，请先定义它，然后将其传入。

/**
 * This function creates an alert box and resets value of the form
 * @param {event} click when the submit button is pressed
 */
const clickHandler = (event) => {
  alert('Thanks for your wonderful input.');
  document.getElementById('sleekform').reset();
  document.getElementById('sleektexta').value = '';
};

document.getElementById('submitB').addEventListener('click', clickHandler);

JSDoc 的目的是记录 您的 JavaScript 应用程序或库的 API （强调我的）