另一个黑客

我创建了一个脚本来读取文件包。Json作为句柄模板的上下文。

代码如下，以防有人发现这种方法有用:

const templateData = require('../package.json');
const Handlebars = require('handlebars');
const fs = require('fs-extra');
const outputPath = __dirname + '/../package-json-comments.md';
const srcTemplatePath = __dirname + '/package-json-comments/package-json-comments.hbs';

Handlebars.registerHelper('objlist', function() {
  // The first argument is an object, and the list is a set of keys for that obj
  const obj = arguments[0];
  const list = Array.prototype.slice.call(arguments, 1).slice(0,-1);

  const mdList = list.map(function(k) {
    return '* ' + k + ': ' + obj[k];
  });

  return new Handlebars.SafeString(mdList.join("\n"));
});

fs.readFile(srcTemplatePath, 'utf8', function(err, srcTemplate){
  if (err) throw err;
  const template = Handlebars.compile(srcTemplate);
  const content = template(templateData);

  fs.writeFile(outputPath, content, function(err) {
    if (err) throw err;
  });
});

句柄模板文件package-json-comments.hbs

### Dependency Comments
For package: {{ name }}: {{version}}

#### Current Core Packages
should be safe to update
{{{objlist dependencies
           "@material-ui/core"
           "@material-ui/icons"
           "@material-ui/styles"
}}}

#### Lagging Core Packages
breaks current code if updated
{{{objlist dependencies
           "amazon-cognito-identity-js"
}}}

#### Major version change
Not tested yet
{{{objlist dependencies
           "react-dev-utils"
           "react-redux"
           "react-router"
           "redux-localstorage-simple"

}}}

受这条线索的启发，下面是我们正在使用的:

{
  "//dependencies": {
    "crypto-exchange": "Unified exchange API"
  },
  "dependencies": {
    "crypto-exchange": "^2.3.3"
  },
  "//devDependencies": {
    "chai": "Assertions",
    "mocha": "Unit testing framwork",
    "sinon": "Spies, Stubs, Mocks",
    "supertest": "Test requests"
  },
  "devDependencies": {
    "chai": "^4.1.2",
    "mocha": "^4.0.1",
    "sinon": "^4.1.3",
    "supertest": "^3.0.0"
  }
}

NPS(节点包脚本)为我解决了这个问题。它允许你把NPM脚本放到一个单独的JavaScript文件中，在那里你可以添加大量的注释和任何其他你需要的JavaScript逻辑。 https://www.npmjs.com/package/nps

来自我的一个项目的package-scripts.js示例

module.exports = {
  scripts: {
    // makes sure e2e webdrivers are up to date
    postinstall: 'nps webdriver-update',

    // run the webpack dev server and open it in browser on port 7000
    server: 'webpack-dev-server --inline --progress --port 7000 --open',

    // start webpack dev server with full reload on each change
    default: 'nps server',

    // start webpack dev server with hot module replacement
    hmr: 'nps server -- --hot',

    // generates icon font via a gulp task
    iconFont: 'gulp default --gulpfile src/deps/build-scripts/gulp-icon-font.js',

    // No longer used
    // copyFonts: 'copyfiles -f src/app/glb/font/webfonts/**/* dist/1-0-0/font'
  }
}

我只是做了一个本地安装npm安装nps -save-dev，并把它放在我的包。json脚本。

"scripts": {
    "start": "nps",
    "test": "nps test"
}

总结一下这些答案:

添加一个名为//的顶级字段，其中包含一个注释字符串。这是可行的，但它很糟糕，因为你不能把评论放在他们正在评论的东西附近。 添加多个以//开头的顶级字段，例如包含注释字符串的//dependencies。这样更好，但仍然只允许您做顶级注释。不能注释单个依赖项。 在脚本中添加echo命令。这是可行的，但它很糟糕，因为您只能在脚本中使用它。

这些解决方案的可读性也都不是很好。它们增加了大量的视觉干扰，ide不会用语法将它们作为注释突出显示。

我认为唯一合理的解决方案是生成包。Json从另一个文件。最简单的方法是将JSON写成JavaScript，然后使用Node.js将其写入package.json。将该文件保存为package.json。chmod +x它，然后你可以运行它来生成你的package。json。

#!/usr/bin/env node

import { writeFileSync } from "fs";

const config = {
  // TODO: Think of better name.
  name: "foo",
  dependencies: {
    // Bar 2.0 does not work due to bug 12345.
    bar: "^1.2.0",
  },
  // Look at these beautify comments. Perfectly syntax highlighted, you
  // can put them anywhere and there no risk of some tool removing them.
};

writeFileSync("package.json", JSON.stringify({
    "//": "This file is \x40generated from package.json.mjs; do not edit.",
    ...config
  }, null, 2));

它使用//键来警告人们不要编辑它。\x40生成是故意的。它变成了@generated in package。Json，这意味着一些代码审查系统将在默认情况下崩溃该文件。

这是构建系统中的一个额外步骤，但它胜过这里的所有其他hack。

以下是我对包内评论的看法。Json / bower.json:

我有文件package.json.js，其中包含一个脚本，导出实际的package.json。运行脚本将覆盖旧包。Json并告诉我它所做的更改，完美地帮助你跟踪NPM所做的自动更改。这样，我甚至可以通过编程方式定义我想要使用的包。

最新的Grunt任务如下: https://gist.github.com/MarZab/72fa6b85bc9e71de5991

我对JSON中没有注释的沮丧之处的看法。我创建了新节点，以它们所引用的节点命名，但以下划线作为前缀。这是不完美的，但功能。

{
  "name": "myapp",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "react": "^16.3.2",
    "react-dom": "^16.3.2",
    "react-scripts": "1.1.4"
  },
  "scripts": {
    "__start": [
        "a note about how the start script works"
    ],
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test --env=jsdom",
    "eject": "react-scripts eject"
  },
  "__proxy": [
    "A note about how proxy works",
    "multilines are easy enough to add"
  ],
  "proxy": "http://server.whatever.com:8000"
}