Add some comments to proposal modules

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

@@ -222,7 +222,8 @@ decl_module! {
             )?;
         }
 
-        /// Create 'Runtime upgrade' proposal type.
+        /// Create 'Runtime upgrade' proposal type. Runtime upgrade can be initiated only by
+        /// members from the hardcoded list `RuntimeUpgradeProposalAllowedProposers`
         pub fn create_runtime_upgrade_proposal(
             origin,
             member_id: MemberId<T>,
@@ -289,7 +290,6 @@ decl_module! {
             )?;
         }
 
-
         /// Create 'Set council mint capacity' proposal type. This proposal uses `set_mint_capacity()`
         /// extrinsic from the `governance::council` module.
         pub fn create_set_council_mint_capacity_proposal(
@@ -580,7 +580,7 @@ impl<T: Trait> Module<T> {
             stake_balance,
         )?;
 
-        <proposal_discussion::Module<T>>::ensure_can_create_thread(&title, member_id.clone())?;
+        <proposal_discussion::Module<T>>::ensure_can_create_thread(member_id.clone(), &title)?;
 
         let discussion_thread_id =
             <proposal_discussion::Module<T>>::create_thread(member_id, title.clone())?;

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

@@ -1,13 +1,43 @@
-//! Proposals discussion module for the Joystream platform. Version 2.
-//! Contains discussion subsystem for the proposals engine.
+//! # Proposals discussion module
+//! Proposals `discussion` module for the Joystream platform. Version 2.
+//! Contains discussion subsystem of the proposals.
 //!
-//! Supported extrinsics:
-//! - add_post - adds a post to existing discussion thread
-//! - update_post - updates existing post
+//! ## Overview
 //!
-//! Public API:
-//! - create_discussion - creates a discussion
-//! - ensure_can_create_thread - ensures safe thread creation
+//! The proposals discussion module is used by the codex module to provide a platform for discussions
+//! about different proposals. It allows to create discussion threads and then add and update related
+//! posts.
+//!
+//! ## Supported extrinsics
+//! - [add_post](./struct.Module.html#method.add_post) - adds a post to existing discussion thread
+//! - [update_post](./struct.Module.html#method.update_post) - updates existing post
+//!
+//! ## Public API methods
+//! - [create_thread](./struct.Module.html#method.create_thread) - creates a discussion thread
+//! - [ensure_can_create_thread](./struct.Module.html#method.ensure_can_create_thread) - ensures safe thread creation
+//!
+//! ## Usage
+//!
+//! ```
+//! use srml_support::{decl_module, dispatch::Result};
+//! use system::ensure_root;
+//! use substrate_proposals_discussion_module::{self as discussions};
+//!
+//! pub trait Trait: discussions::Trait + membership::members::Trait {}
+//!
+//! decl_module! {
+//! 	pub struct Module<T: Trait> for enum Call where origin: T::Origin {
+//! 		pub fn create_discussion(origin, title: Vec<u8>, author_id : T::MemberId) -> Result {
+//! 			ensure_root(origin)?;
+//! 			<discussions::Module<T>>::ensure_can_create_thread(author_id, &title)?;
+//! 			<discussions::Module<T>>::create_thread(author_id, title)?;
+//! 			Ok(())
+//! 		}
+//! 	}
+//! }
+//! # fn main() { }
+//! ```
+
 //!
 
 // Ensure we're `no_std` when compiling for Wasm.
@@ -84,6 +114,7 @@ pub trait Trait: system::Trait + membership::members::Trait {
 }
 
 decl_error! {
+    /// Discussion module predefined errors
     pub enum Error {
         /// Author should match the post creator
         NotAuthor,
@@ -242,18 +273,13 @@ decl_module! {
 }
 
 impl<T: Trait> Module<T> {
-    // Wrapper-function over system::block_number()
-    fn current_block() -> T::BlockNumber {
-        <system::Module<T>>::block_number()
-    }
-
     /// Create the discussion thread. Cannot add more threads than 'predefined limit = MaxThreadInARowNumber'
     /// times in a row by the same author.
     pub fn create_thread(
         thread_author_id: MemberId<T>,
         title: Vec<u8>,
     ) -> Result<T::ThreadId, Error> {
-        Self::ensure_can_create_thread(&title, thread_author_id.clone())?;
+        Self::ensure_can_create_thread(thread_author_id.clone(), &title)?;
 
         let next_thread_count_value = Self::thread_count() + 1;
         let new_thread_id = next_thread_count_value;
@@ -278,27 +304,13 @@ impl<T: Trait> Module<T> {
         Ok(thread_id)
     }
 
-    // returns incremented thread counter if last thread author equals with provided parameter
-    fn get_updated_thread_counter(author_id: MemberId<T>) -> ThreadCounter<MemberId<T>> {
-        // if thread counter exists
-        if let Some(last_thread_author_counter) = Self::last_thread_author_counter() {
-            // if last(previous) author is the same as current author
-            if last_thread_author_counter.author_id == author_id {
-                return last_thread_author_counter.increment();
-            }
-        }
-
-        // else return new counter (set with 1 thread number)
-        ThreadCounter::new(author_id)
-    }
-
     /// Ensures thread can be created.
     /// Checks:
     /// - title is valid
     /// - max thread in a row by the same author
     pub fn ensure_can_create_thread(
-        title: &[u8],
         thread_author_id: MemberId<T>,
+        title: &[u8],
     ) -> DispatchResult<Error> {
         ensure!(!title.is_empty(), Error::EmptyTitleProvided);
         ensure!(
@@ -317,3 +329,24 @@ impl<T: Trait> Module<T> {
         Ok(())
     }
 }
+
+impl<T: Trait> Module<T> {
+    // Wrapper-function over system::block_number()
+    fn current_block() -> T::BlockNumber {
+        <system::Module<T>>::block_number()
+    }
+
+    // returns incremented thread counter if last thread author equals with provided parameter
+    fn get_updated_thread_counter(author_id: MemberId<T>) -> ThreadCounter<MemberId<T>> {
+        // if thread counter exists
+        if let Some(last_thread_author_counter) = Self::last_thread_author_counter() {
+            // if last(previous) author is the same as current author
+            if last_thread_author_counter.author_id == author_id {
+                return last_thread_author_counter.increment();
+            }
+        }
+
+        // else return new counter (set with 1 thread number)
+        ThreadCounter::new(author_id)
+    }
+}

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

@@ -128,6 +128,7 @@ decl_event!(
 );
 
 decl_error! {
+    /// Engine module predefined errors
     pub enum Error {
         /// Proposal cannot have an empty title"
         EmptyTitleProvided,