Harmonize NValue and NValue' notations, add doc ad COMPLETE annotations to patterns.

[layus]

This should probably be considered as a draft.

I was investigating out NValue representation. It turns out that an NValue is a (Free NValue') but that NValue' constructor is NValue. Went around to turn the NValue' constructor to be NValue', and it turns there is only a few places where the change has an impact.

I also added some hands-on documentation on the tricky fiddling we do in there, with many type variables ultimately representing the same thing, but not at declaration time.

I would welcome contributions or pointers to proper haskell in-code documentation.

[Anton-Latukha]

Nice, indeed. There was some puzzlement there before. Now we see it is NValue' there.

+====

About documentation:
The best live examples for documentation for the project that know of is https://github.com/kowainik/relude, there complete documentation and then more. Over kowainik projects overall they keep extremely good documentation, so they ironed-out how to use the majority of the Haddock features and layouts. Those sources are a good example to look into for some particularities of the practice.

One thing that I would differ with them, they section the imports, while I prefer sectioning the source code, since then people have structural awareness of where they are and what the main theme of the code block while reading the code and working in the source files. And that simple source outlining during work gives organization overall, a peace of mind, structural folding, editing:

Screenshot

It was #555 in the past.

About Haddocks, of course, the practice makes perfect. Myself still learning the specific details of Haddock.

Also, you've see probably some of my Value docs, I knew they were corny at the time of writing, but they came out too corny 🤣.

If you consider the patch a draft, then lock it in as a draft. Making the patch ready for merge and right-away stating in the head post that it is a draft - sends opposite messages. Why it is a draft, I see it complete. Probably you consider it as a draft, since docs can be improved.

I began to see, like the Kernel team says that security bugs are just regular bugs, that the documentation process is just code refactoring, meaning that it is sneaked-in duringx the main work. Refactors to docs are even lighter questions to the refactors to code and they both a kinda moral, sanitary, and effective necessity - the most effective way to go about them is to do the docs and code refactors as drive-by improvements into the patches during main work.

For me it looks good to merge. As personally with docs I adhere to the Wiki community post-editing and the rule: having documentation is better than not having it. And polishing the docs in the environment of merge requests I consider it to be overall a very counter-productive and socially awkward process and awkward overall. Rather then doing that, I like saying "thank you" and merging the improvements to docs.

Saying "thanks" and eagerly merging docs also goes into approaching to docs as code refactoring.

Even go further - saying that if a person here was promoted to be a maintainers, that person is qualified enough to give them carte blanche to self-merge docs. In that way, the docs processes and quality would ramp up greatly. Up until the world would start notifying us and shown that the changes to that are required.