Update comments

runtime-modules/proposals/codex/src/lib.rs

@@ -1,12 +1,12 @@
 //! # Proposals codex module
 //! Proposals `codex` module for the Joystream platform. Version 2.
-//! Component of the proposals system. Contains preset proposal types.
+//! Component of the proposals system. It contains preset proposal types.
 //!
 //! ## Overview
 //!
-//! The proposals codex module serves as facade and entry point of the proposals system. It uses
+//! The proposals codex module serves as a facade and entry point of the proposals system. It uses
 //! proposals `engine` module to maintain a lifecycle of the proposal and to execute proposals.
-//! During the proposal creation `codex` also create a discussion thread using the `discussion`
+//! During the proposal creation, `codex` also create a discussion thread using the `discussion`
 //! proposals module. `Codex` uses predefined parameters (eg.:`voting_period`) for each proposal and
 //! encodes extrinsic calls from dependency modules in order to create proposals inside the `engine`
 //! module. For each proposal, [its crucial details](./enum.ProposalDetails.html) are saved to the

runtime-modules/proposals/discussion/src/lib.rs

@@ -1,6 +1,6 @@
 //! # Proposals discussion module
 //! Proposals `discussion` module for the Joystream platform. Version 2.
-//! Contains discussion subsystem of the proposals.
+//! It contains discussion subsystem of the proposals.
 //!
 //! ## Overview
 //!
@@ -9,7 +9,7 @@
 //! posts.
 //!
 //! ## Supported extrinsics
-//! - [add_post](./struct.Module.html#method.add_post) - adds a post to existing discussion thread
+//! - [add_post](./struct.Module.html#method.add_post) - adds a post to an existing discussion thread
 //! - [update_post](./struct.Module.html#method.update_post) - updates existing post
 //!
 //! ## Public API methods

runtime-modules/proposals/engine/src/lib.rs

@@ -1,24 +1,35 @@
 //! # Proposals engine module
 //! Proposals `engine` module for the Joystream platform. Version 2.
-//! Main component of the proposals system. Provides methods and extrinsics to create and
+//! The main component of the proposals system. Provides methods and extrinsics to create and
 //! vote for proposals, inspired by Parity **Democracy module**.
 //!
 //! ## Overview
-//! Proposals `engine` module provides abstract mechanism to work with proposals: creation, voting,
+//! Proposals `engine` module provides an abstract mechanism to work with proposals: creation, voting,
 //! execution, canceling, etc. Proposal execution demands serialized _Dispatchable_ proposal code.
-//! It could be any _Dispatchable_ + _Parameter_ type, but most likely it would be serialized (via
-//! Parity _codec_ crate) extrisic call. Proposal stage can be described by its [status](./enum.ProposalStatus.html).
+//! It could be any _Dispatchable_ + _Parameter_ type, but most likely, it would be serialized (via
+//! Parity _codec_ crate) extrisic call. A proposal stage can be described by its [status](./enum.ProposalStatus.html).
 //!
 //! ## Proposal lifecycle
 //! When a proposal passes [checks](./struct.Module.html#method.ensure_create_proposal_parameters_are_valid)
 //! for its [parameters](./struct.ProposalParameters.html) - it can be [created](./struct.Module.html#method.create_proposal).
-//! Newly created proposal has _Active_ status. The proposal can be voted on or canceled during its
-//! _voting period_. Votes can be [different](./enum.VoteKind.html). When proposal gets enough votes
+//! The newly created proposal has _Active_ status. The proposal can be voted on or canceled during its
+//! _voting period_. Votes can be [different](./enum.VoteKind.html). When the proposal gets enough votes
 //! to be slashed or approved or _voting period_ ends - the proposal becomes _Finalized_. If the proposal
 //! got approved and _grace period_ passed - the  `engine` module tries to execute the proposal.
 //! The final [approved status](./enum.ApprovedProposalStatus.html) of the proposal defines
-//! an overall proposal outcome. The proposal can also be [vetoed](./struct.Module.html#method.veto_proposal)
+//! an overall proposal outcome.
+//!
+//! ### Notes
+//!
+//! - The proposal can be [vetoed](./struct.Module.html#method.veto_proposal)
 //! anytime before the proposal execution by the _sudo_.
+//! - When the proposal is created with some stake - refunding on proposal finalization with
+//! different statuses should be accomplished from the external handler from the _stake module_
+//! (_StakingEventsHandler_). Such a handler should call
+//! [refund_proposal_stake](./struct.Module.html#method.refund_proposal_stake) callback function.
+//! - If the _council_ got reelected during the proposal _voting period_ the external handler calls
+//! [reset_active_proposals](./trait.Module.html#method.reset_active_proposals) function and
+//! all voting results get cleared.
 //!
 //! ### Important abstract types to be implemented
 //! Proposals `engine` module has several abstractions to be implemented in order to work correctly.
@@ -28,9 +39,9 @@
 //! the council size
 //! - _ProposerOriginValidator_ - ensure valid proposer identity. Proposers should have permissions
 //! to create a proposal: they should be members of the Joystream.
-//! - [StakeHandlerProvider](./trait.StakeHandlerProvider.html) - defines interface for the staking.
+//! - [StakeHandlerProvider](./trait.StakeHandlerProvider.html) - defines an interface for the staking.
 //!
-//! Full list of the abstractions can be found [here](./trait.Trait.html).
+//! A full list of the abstractions can be found [here](./trait.Trait.html).
 //!
 //! ### Supported extrinsics
 //! - [vote](./struct.Module.html#method.vote) - registers a vote for the proposal
@@ -46,14 +57,19 @@
 //! ## Usage
 //!
 //! ```
-//! use srml_support::{decl_module, dispatch::Result};
+//! use srml_support::{decl_module, dispatch::Result, print};
 //! use system::ensure_signed;
+//! use codec::Encode;
 //! use substrate_proposals_engine_module::{self as engine, ProposalParameters};
 //!
 //! pub trait Trait: engine::Trait + membership::members::Trait {}
 //!
 //! decl_module! {
 //!     pub struct Module<T: Trait> for enum Call where origin: T::Origin {
+//!         fn executable_proposal(origin) {
+//!             print("executed!");
+//!         }
+//!
 //!         pub fn create_spending_proposal(
 //!             origin,
 //!             proposer_id: T::MemberId,
@@ -61,8 +77,9 @@
 //!             let account_id = ensure_signed(origin)?;
 //!             let parameters = ProposalParameters::default();
 //!             let title = b"Spending proposal".to_vec();
-//!             let description = b"We need to spend some tokens to support the working group lead.".to_vec();
-//!             let encoded_proposal_code = Vec::new();
+//!             let description = b"We need to spend some tokens to support the working group lead."
+//!                 .to_vec();
+//!             let encoded_proposal_code = <Call<T>>::executable_proposal().encode();
 //!
 //!             <engine::Module<T>>::ensure_create_proposal_parameters_are_valid(
 //!                 &parameters,