fix all _examples to the newest mvc, add comments to those examples and add a package-level .Configure in order to make it easier for new users. Add a deprecated panic if app.Controller is used with a small tutorial and future resource link so they can re-write their mvc app's definitions

Former-commit-id: bf07696041be9e3d178ce3c42ccec2df4bfdb2af

mvc/di/TODO.txt

@@ -0,0 +1,11 @@
+I can do one of the followings to this "di" folder when I finish the cleanup and document it a bit,
+although I'm sick I will try to finish it tomorrow.
+
+End-users don't need this.
+1) So, rename this to "internal".
+
+I don't know if something similar exist in Go,
+it's a dependency injection framework at the end, and a very fast one.
+
+2) So I'm thinking to push it to a different repo,
+  like https://github.com/kataras/di or even to my small common https://github.com/kataras/pkg collection. 

mvc/di/di.go

@@ -57,15 +57,14 @@ func (d *D) Clone() *D {
 // with the injector's `Inject` and `InjectElem` methods.
 func (d *D) Struct(s interface{}) *StructInjector {
 	if s == nil {
-		return nil
+		return &StructInjector{HasFields: false}
 	}
-	v := ValueOf(s)
 
 	return MakeStructInjector(
-		v,
+		ValueOf(s),
 		d.hijacker,
 		d.goodFunc,
-		d.Values...,
+		d.Values.CloneWithFieldsOf(s)...,
 	)
 }
 
@@ -75,6 +74,10 @@ func (d *D) Struct(s interface{}) *StructInjector {
 // to the function's input argument when called
 // with the injector's `Fill` method.
 func (d *D) Func(fn interface{}) *FuncInjector {
+	if fn == nil {
+		return &FuncInjector{Valid: false}
+	}
+
 	return MakeFuncInjector(
 		ValueOf(fn),
 		d.hijacker,

mvc/di/struct.go

@@ -5,10 +5,10 @@ import (
 	"reflect"
 )
 
-type State uint8
+type Scope uint8
 
 const (
-	Stateless State = iota
+	Stateless Scope = iota
 	Singleton
 )
 
@@ -29,7 +29,7 @@ type (
 		// see `setState`.
 		HasFields bool
 		CanInject bool // if any bindable fields when the state is NOT singleton.
-		State     State
+		Scope     Scope
 	}
 )
 
@@ -121,13 +121,13 @@ func (s *StructInjector) setState() {
 	// if the number of static values binded is equal to the
 	// total struct's fields(including unexported fields this time) then set as singleton.
 	if staticBindingsFieldsLength == allStructFieldsLength {
-		s.State = Singleton
+		s.Scope = Singleton
 		// the default is `Stateless`, which means that a new instance should be created
 		//  on each inject action by the caller.
 		return
 	}
 
-	s.CanInject = s.State == Stateless && s.HasFields
+	s.CanInject = s.Scope == Stateless && s.HasFields
 }
 
 // fill the static bindings values once.
@@ -177,15 +177,15 @@ func (s *StructInjector) InjectElem(destElem reflect.Value, ctx ...reflect.Value
 	}
 }
 
-func (s *StructInjector) New() reflect.Value {
-	if s.State == Singleton {
+func (s *StructInjector) Acquire() reflect.Value {
+	if s.Scope == Singleton {
 		return s.initRef
 	}
 	return reflect.New(s.elemType)
 }
 
-func (s *StructInjector) NewAsSlice() []reflect.Value {
-	if s.State == Singleton {
+func (s *StructInjector) AcquireSlice() []reflect.Value {
+	if s.Scope == Singleton {
 		return s.initRefAsSlice
 	}
 	return []reflect.Value{reflect.New(s.elemType)}

mvc/di/values.go

@@ -2,16 +2,6 @@ package di
 
 import "reflect"
 
-type ValuesReadOnly interface {
-	// Has returns true if a binder responsible to
-	// bind and return a type of "typ" is already registered to this controller.
-	Has(value interface{}) bool
-	// Len returns the length of the values.
-	Len() int
-	// Clone returns a copy of the current values.
-	Clone() Values
-}
-
 type Values []reflect.Value
 
 func NewValues() Values {
@@ -30,7 +20,7 @@ func (bv Values) Clone() Values {
 }
 
 // CloneWithFieldsOf will return a copy of the current values
-// plus the "v" struct's fields that are filled(non-zero) by the caller.
+// plus the "s" struct's fields that are filled(non-zero) by the caller.
 func (bv Values) CloneWithFieldsOf(s interface{}) Values {
 	values := bv.Clone()