docs(nns): Resurrect request and response comments. (#3671)

Recently, we deleted a bunch of request and response types from NNS
governance.proto. Although the types themselves are not necessary, the
comments contained valuable information, which could (and should) have
been copied to governance.did. This PR corrects that oversight.

# References

Types deleted in recent PRs:

* [ListNeurons]
* [ManageNeuronResponse]
* [NeuronInfo]

[ListNeurons]: #3546
[ManageNeuronResponse]: #3573
[NeuronInfo]: #3639

Author: daniel-wong-dfinity-org

rs/nns/governance/canister/governance.did

@@ -434,18 +434,37 @@ type ListKnownNeuronsResponse = record {
   known_neurons : vec KnownNeuron;
 };
 
+// Parameters of the list_neurons method.
 type ListNeurons = record {
-  include_public_neurons_in_full_neurons : opt bool;
+  // These fields select neurons to be in the result set.
   neuron_ids : vec nat64;
-  include_empty_neurons_readable_by_caller : opt bool;
   include_neurons_readable_by_caller : bool;
+
+  // Only has an effect when include_neurons_readable_by_caller.
+  include_empty_neurons_readable_by_caller : opt bool;
+
+  // When a public neuron is a member of the result set, include it in the
+  // full_neurons field (of ListNeuronsResponse). This does not affect which
+  // neurons are part of the result set.
+  include_public_neurons_in_full_neurons : opt bool;
+
   page_number: opt nat64;
   page_size: opt nat64;
 };
 
+// Output of the list_neurons method.
 type ListNeuronsResponse = record {
+  // Per the NeuronInfo type, this is a redacted view of the neurons in the
+  // result set consisting of information that require no special privileges to
+  // view.
   neuron_infos : vec record { nat64; NeuronInfo };
+
+  // If the caller has the necessary special privileges (or the neuron is
+  // public, and the request sets include_public_neurons_in_full_neurons to
+  // true), then all the information about the neurons in the result set is made
+  // available here.
   full_neurons : vec Neuron;
+
   total_pages_available: opt nat64;
 };
 
@@ -493,6 +512,8 @@ type MakingSnsProposal = record {
   proposer_id : opt NeuronId;
 };
 
+// Not to be confused with ManageNeuronRequest. (Yes, this is very structurally
+// similar to that, but not actually exactly equivalent.)
 type ManageNeuron = record {
   id : opt NeuronId;
   command : opt Command;
@@ -518,13 +539,22 @@ type ManageNeuronCommandRequest = variant {
   // KEEP THIS IN SYNC WITH COMMAND!
 };
 
+// Parameters of the manage_neuron method.
 type ManageNeuronRequest = record {
-  id : opt NeuronId;
-  command : opt ManageNeuronCommandRequest;
+  // Which neuron to operate on.
   neuron_id_or_subaccount : opt NeuronIdOrSubaccount;
+
+  // What operation to perform on the neuron.
+  command : opt ManageNeuronCommandRequest;
+
+  // Deprecated. Use neuron_id_or_subaccount instead.
+  id : opt NeuronId;
 };
 
+// Output of the manage_neuron method.
 type ManageNeuronResponse = record {
+  // Corresponds to the command field in ManageNeuronRequest, which determines
+  // what operation was performed.
   command : opt Command_1;
 };
 
@@ -730,14 +760,26 @@ type NeuronInFlightCommand = record {
   timestamp : nat64;
 };
 
-// In general, this is a subset of Neuron.
+// A limit view of Neuron that allows some aspects of all neurons to be read by
+// anyone (i.e. without having to be the neuron's controller nor one of its
+// hotkeys).
+//
+// As such, the meaning of each field in this type is generally the same as the
+// one of the same (or at least similar) name in Neuron.
 type NeuronInfo = record {
   dissolve_delay_seconds : nat64;
   recent_ballots : vec BallotInfo;
   neuron_type : opt int32;
   created_timestamp_seconds : nat64;
   state : int32;
+
+  // The amount of ICP (and staked maturity) locked in this neuron.
+  //
+  // This is the foundation of the neuron's voting power.
+  //
+  // cached_neuron_stake_e8s - neuron_fees_e8s + staked_maturity_e8s_equivalent
   stake_e8s : nat64;
+
   joined_community_fund_timestamp_seconds : opt nat64;
   retrieved_at_timestamp_seconds : nat64;
   visibility : opt int32;
@@ -752,6 +794,7 @@ type NeuronInfo = record {
   // Now that this is set to deciding_voting_power, this actually does get
   // zeroed out.
   voting_power : nat64;
+
   voting_power_refreshed_timestamp_seconds : opt nat64;
   deciding_voting_power : opt nat64;
   potential_voting_power : opt nat64;