Developer Documentation Needed on Proper Usage of Reference Counters

[shawntabrizi]

After a review of: paritytech/substrate#8221

The auditing team said it would be important to document how to correctly use the different reference counters so that third party teams do not make mistakes and get accounts into locked states.

A technical writer can work with me to get a better understanding of reference counters and then work to write up documentation which covers this within the DevHub or even the inline documentation.

[jimmychu0807]

let me work on this next week.

[jimmychu0807]

• Self-sufficient account ref-counting paritytech/substrate#8221
• Assets: Remove zombies, introduce approvals paritytech/substrate#8220
• When to inc_ref / dec_ref? paritytech/substrate#5255

@shawntabrizi I start to work on this. I went over Substrate PR #8221, see the keys are on having { consumers, providers, sufficients } in AccountInfo. I also see the intricate logic when incrementing and decrementing each of them in the dec_{providers, consumers, sufficients}, and inc_{providers, consumers, sufficients} methods. I check and see the test cases.

But I wonder how should this be documented? Current there is almost no use of inc_sufficients, a few uses of inc_providers in the src, and moderate uses of inc_consumers by frame_balances, pallet_recovery. It seems to me this is some kind of internal state tracking variables. I am thinking what is a good approach of writing the doc for these three variables so runtime developers can start using them in their work?

[shawntabrizi]