Build a compiler documentation and a testable specification

[ringabout]

The Neon Genesis Evolution Plan

北海虽赊，扶摇可接；东隅已逝，桑榆非晚。
It is better late than never.

Introduction

Documentation and specifications are the long-standing obstacles which stop the Nim language from gaining the popularity it deserves. Documentation helps developers learn the language. A specification clarifies how the language works.

The RFC is intended to be progressive and grows gradually. We start from commenting the compiler code. A testable specification roll out at the same time. Then the comments and the specification should help form a book summarizing how the Nim compiler works.

Documentation

Functions without comments in the compiler and the standard library tend to be hard to understand. Comments help developers gain the insights of why the code is written like this and how it probably works.
The Nim CI should have a measure to calculate the comment ratio of the compiler and the standard library. The comment ratio is defined as comments lines / total lines (excluding empty lines).

Comments could be obsolete and meaningless. However, It is worthwhile updating the comment periodically since the code and comments will be read thousands of times.

• add the comment ratio metric to the Nim CI

The Compiler Documentation

The contribution of the compiler documentation should be in the form of a pull request. The pull request should document a module or a component consisting of a series of related functions in the Nim compiler.

• mConStrStr

Specification

Write a testable specification for the Nim manual. A specification should describe what should work or what should fail, with abundant examples. The generated HTML should be placed at the spec directory. The Nim manual should link the specification at the appropriate place.