You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
jakmeier opened this issue
Nov 9, 2022
· 4 comments
Labels
C-docsCategory: documentation, including rustdoc, nomicon, and docs.nearprotocol.comNodeNode teamT-nodeTeam: issues relevant to the node experience team
I believe we currently have no documentation on what each field in config.json does.
Even the code does not really contain comments, so how would a node operator find about the details?
The text was updated successfully, but these errors were encountered:
jakmeier
added
C-docs
Category: documentation, including rustdoc, nomicon, and docs.nearprotocol.com
T-node
Team: issues relevant to the node experience team
labels
Nov 9, 2022
TBH, I don't know a good format for "automated" JSON documentation. In theory, it is json schema, but in practice it's human-hostile.
If I were to document some JSON, I'd probably go for creating a TypeScript file with the type definiton for it.
My suggestion for specific improvement would be:
Move all structs defining config.json into a single crate. Today, the format is split across a tone of different crates, which makes it hard to understand it a glance.
Remove json serilization of config from other crates
Move all config in a single file, and ensure that this file doesn't contain anything besides config
Document the file and use it as a source of truth for config.
I agree with you in terms of finding a good long-term solution. But in the short-term, I'd really just like a place where we can point node maintainers that ask what the field in this field do.
Context: Today during protocol office hour, someone told me about their need to increase trie_viewer_state_size_limit to make their view calls possible. And they wanted to know where they can learn about what these fields in config.json mean. I was a bit shocked to not find anything on https://near-nodes.io/ and not even in the code.
I sort-of feel that moving everything into a single file is a pre-req for anything smarter than "manually syncing docs with near-nodes.io". Which might not be too bad, actually.
C-docsCategory: documentation, including rustdoc, nomicon, and docs.nearprotocol.comNodeNode teamT-nodeTeam: issues relevant to the node experience team
I believe we currently have no documentation on what each field in
config.json
does.Even the code does not really contain comments, so how would a node operator find about the details?
Can we fix that? Adding comments in code would be a good start, great would be to also add some docs to https://near-nodes.io/ or even just our internal docs https://near.github.io/nearcore/
The text was updated successfully, but these errors were encountered: