Apply suggestions from code review

Co-Authored-By: Aditya <adityasripal@gmail.com>

store/mem/store.go

@@ -16,8 +16,8 @@ var (
 	_ types.Committer = (*Store)(nil)
 )
 
-// Store implements an in-memory only KVStore. Entries are peresistent between
-// commits and thus between blocks.
+// Store implements an in-memory only KVStore. Entries are persisted between
+// commits and thus between blocks. State in Memory store is not committed as part of app state but maintained privately by each node
 type Store struct {
 	dbadapter.Store
 }

x/capability/docs/README.md

@@ -10,15 +10,15 @@ The keeper maintains two states: persistent and ephemeral in-memory. The persist
 store maintains a globally unique auto-incrementing index and a mapping from
 capability index to a set of capability owners that are defined as a module and
 capability name tuple. The in-memory ephemeral state keeps track of the actual
-capabilities with both forward and reverse indexes. The forward index maps
+capabilities, represented as addresses in local memory, with both forward and reverse indexes. The forward index maps
 module name and capability tuples to the capability name. The reverse index maps
 between the module and capability name and the capability itself.
 
 The keeper allows the creation of "scoped" sub-keepers which are tied to a particular
 module by name. Scoped keepers must be created at application initialization and
 passed to modules, which can then use them to claim capabilities they receive and
 retrieve capabilities which they own by name, in addition to creating new capabilities
-& authenticating capabilities passed by other modules.
+& authenticating capabilities passed by other modules. A scoped keeper cannot escape its scope, so a module cannot interfere with or inspect capabilities owned by other modules.
 
 The keeper provides no other core functionality that can be found in other modules
 like queriers, REST and CLI handlers, and genesis state.
@@ -75,13 +75,12 @@ allows a module to claim a capability key which it has received from another
 module so that future `GetCapability` calls will succeed. `ClaimCapability` MUST
 be called if a module which receives a capability wishes to access it by name in
 the future. Again, capabilities are multi-owner, so if multiple modules have a
-single Capability reference, they will all own it.
+single Capability reference, they will all own it. If a module receives a capability from another module but does not call `ClaimCapability`, it may use it in the executing transaction but will not be able to access it afterwards.
 
 `AuthenticateCapability` can be called by any module to check that a capability
 does in fact correspond to a particular name (the name can be un-trusted user input)
 with which the calling module previously associated it.
 
 `GetCapability` allows a module to fetch a capability which it has previously
 claimed by name. The module is not allowed to retrieve capabilities which it does
-not own. If another module claims a capability, the previously owning module will
-no longer be able to claim it.
+not own.

x/capability/keeper/keeper.go

@@ -166,7 +166,7 @@ func (sk ScopedKeeper) NewCapability(ctx sdk.Context, name string) (types.Capabi
 // true upon success and false upon failure.
 //
 // Note, the capability's forward mapping is indexed by a string which should
-// contain it's unique memory reference.
+// contain its unique memory reference.
 func (sk ScopedKeeper) AuthenticateCapability(ctx sdk.Context, cap types.Capability, name string) bool {
 	memStore := ctx.KVStore(sk.memKey)
 
@@ -201,8 +201,7 @@ func (sk ScopedKeeper) ClaimCapability(ctx sdk.Context, cap types.Capability, na
 
 // GetCapability allows a module to fetch a capability which it previously claimed
 // by name. The module is not allowed to retrieve capabilities which it does not
-// own. If another module claims a capability, the previously owning module will
-// no longer be able to claim it.
+// own.
 func (sk ScopedKeeper) GetCapability(ctx sdk.Context, name string) (types.Capability, bool) {
 	memStore := ctx.KVStore(sk.memKey)