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

Posted 2023-03-11

【中文标题】为啥有些函数会出现在 JSDoc 中而有些函数却没有？

【英文标题】：Why do some functions show up in JSDoc and others don't?为什么有些函数会出现在 JSDoc 中而有些函数却没有？

【发布时间】：2022-01-19 15:09:38

【问题描述】：

这个函数显示在 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] + 50px`) // 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

【问题讨论】：

addEventListener() 正在调用现有函数，而不是定义新函数。

第二件事不是函数……你认为应该显示什么？

所以 JSDoc 仅用于您定义的函数，而不是预先存在的函数和/或库中的函数。

您添加了大量代码。请你把它剪下来，只保留相关的东西吗？ （或者做一些调试）可能是拼写错误，或者语法错误，导致jsdoc无法显示函数。

另外，第一个函数有两个cmets？我认为这是一个错误。

【参考方案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 （强调我的）

【讨论】：

谢谢你，但是刷新 JSDoc 文件时，这仍然不显示。然后我将 const 更改为 function，但也没有做任何事情

当我在没有选项的情况下运行默认的 jsdoc cli 时，该函数是否被正确记录？请您更新显示minimal reproducible example的问题？

该代码独立工作，但与其他功能结合使用，它不会出现在 html 文件中。我将编辑具有完整功能的帖子。

@YanatMengisha 更新有意义吗？