Avoid incorrect or conflicted documentation-like files.

[yangby-cryptape]

Description

Please Answer these Questions before continue.

• As a reviewer, would you check the generated file by yourself, before you click the approval button?
  p.s. I won't.
• Have you ever did that, even once?
  p.s. I haven't.

Continue ...

Documentation has no binding effect, just fake oneself, to pretend that he has done something to keep things right, but actually did nothing. "No-developers-cared", "users-will-be-fooled", "passively-maintained" documentations, like $\text{wanks}$: no one gets benefit except the owner who feel his is huge.

I don't have to imagine a bad case, since I have already experienced those sucked and useless documentations.

Even no documentations are better than incorrect documentations.

I think there are 3 ways which could resolve this problem.

• Add a CI check to check those generated files if they could.
• Generated those source codes in compile-time (build.rs) from the original files if they could.
• Remove all files which are used as documentations, to force users to read the source codes.
  At least, source codes have a better probability to be correct.

☢️ Pay Attention

Incorrect documentations don't due to the developers: how could they know two unrelated files are related?

Concrete Cases

• chore: update CkbType.sol for consistent ABI output with json file #1558

  😱 Be incorrect for half year.

  axon/builtin-contract/system-contract/contracts/libraries/CkbType.sol

  Line 15 in 835cb16

  bytes32 unclesHash;

  p.s. This line is committed 8 months ago in feat: add write interfaces and abi for image cell system contract #909.

  axon/core/executor/src/system_contract/ckb_light_client/abi/ckb_light_client_abi.json

  Line 74 in 835cb16

  "name": "extraHash",

  p.s. This line is committed 6 months ago in refactor: remove outdated cross chain code #1085.

• chore: update ImageCell.sol for consistent ABI output with json file #1567

• refactor: change metadata system contract and add annotation #1449

[Flouse]

Even no documentations are better than incorrect documentations.

I think there are 3 ways which could resolve this problem.

• Add a CI check to check those generated files if they could.
• Generated those source codes in compile-time (build.rs) from the original files if they could.
• Remove all files which are used as documentations, to force users to read the source codes.
  At least, source codes have a better probability to be correct.

Need confirmation before PRs

• @Flouse
• @KaoImin

---

@yangby-cryptape if the solutions are confirmed, would you like to take over this mission?