improve docs (#2068)

* improve decl_storage instance doc

* use decl_event doc accordignly

* automate doc and while allow to extend it on event

* some missed ones

* Update srml/example/src/lib.rs

Co-Authored-By: thiolliere <gui.thiolliere@gmail.com>

* Update srml/support/procedural/src/storage/transformation.rs

substrate/srml/example/src/lib.rs

@@ -72,10 +72,10 @@ decl_storage! {
 	}
 }
 
-/// An event in this module. Events are simple means of reporting specific conditions and
-/// circumstances that have happened that users, Dapps and/or chain explorers would find
-/// interesting and otherwise difficult to detect.
 decl_event!(
+	/// Events are a simple means of reporting specific conditions and
+	/// circumstances that have happened that users, Dapps and/or chain explorers would find
+	/// interesting and otherwise difficult to detect.
 	pub enum Event<T> where B = <T as balances::Trait>::Balance {
 		// Just a normal `enum`, here's a dummy event to ensure it compiles.
 		/// Dummy event, just here so there's a generic type that's used.