godoc: improving godoc

Signed-off-by: Filip Petrov <lombert.p.v@gmail.com>

Author: FilipVPetrov

README.md

@@ -1 +1,10 @@
-# autowire
+# 🔌 autowire [![GoDoc][doc-img]][doc] [![Github release][release-img]][release] [![Go Report Card][report-card-img]][report-card]
+
+[doc-img]: http://img.shields.io/badge/GoDoc-Reference-blue.svg
+[doc]: https://godoc.org/github.com/go-autowire/autowire
+
+[release-img]: https://img.shields.io/github/release/go-autowire/autowire.svg
+[release]: https://github.com/go-autowire/autowire
+
+[report-card-img]: https://goreportcard.com/badge/github.com/go-autowire/autowire
+[report-card]: https://goreportcard.com/report/github.com/go-autowire/autowire

atesting/testing.go

@@ -8,11 +8,39 @@ import (
 	"unicode"
 )
 
+// Spy Function is replacing object field with the one provided in the function as a second argument.
+// Spy Function detects automatically which field could be replaced with the provided one.
+// Important note: In order to traverse fields of the unexported fields we need to implement Getters.
+// As shown inside example package, we are replacing AuditClient with our mock implementation and in order to reach this
+// field we need Getter.
+// Example:
+//   atesting.Spy(application, &TestAuditClient{})
+// Or this is equivalent of
+//   application.UserSvc().SetAuditClient(&TestAuditClient{})
+// Getter UserSvc() is used to access userSvc field, which is unexported. For more information take a look at example package.
+//Parameters of Spy function:
+//   - `v`          : pointer to structure inside which spy object will be applied
+//   - `dependency` : pointer to structure which will be injected
 func Spy(v interface{}, dependency interface{}) {
 	slice := []interface{}{dependency}
 	Spies(v, slice)
 }
 
+// Spies Function is replacing object fields with the list of provided dependencies in the function as a second argument.
+// Spy Function detects automatically which field could be replaced with the provided one in the list of dependencies.
+// Important note: In order to traverse fields of the unexported fields we need to implement Getters.
+// As shown inside example package, we are replacing AuditClient with our mock implementation and in order to reach this
+// field we need Getter.
+// Example:
+//   	atesting.Spies(application, []interface{}{&TestPaymentServiceTest{}, &TestAuditClient{}})
+// Or this is equivalent of
+//   application.UserSvc().SetAuditClient(&TestAuditClient{})
+//   application.UserSvc().PaymentSvc = &TestPaymentServiceTest{}
+// Getter UserSvc() is used to access userSvc field, which is unexported. In case of PaymentSvc it is not required as field PaymentSvc is exported.
+// Parameters of Spies function:
+//   - `v`            : structure inside which spy objects will be applied
+//   - `dependencies` : list of dependencies which will be injected
+// For more information take a look at example package.
 func Spies(v interface{}, dependencies []interface{}) {
 	queue := list.New()
 	queue.PushBack(v)
@@ -38,7 +66,7 @@ func Spies(v interface{}, dependencies []interface{}) {
 							t := reflect.New(dependValue.Type())
 							log.Println("Injecting Spy on dependency by tag " + tag + " will be used " + t.Type().String())
 							autowire.Autowire(dependency)
-							setValue(value, elem, i, dependency)
+							setFieldValue(value, elem, i, dependency)
 						}
 					}
 				}
@@ -61,7 +89,7 @@ func Spies(v interface{}, dependencies []interface{}) {
 	}
 }
 
-func setValue(value reflect.Value, elem reflect.Value, i int, dependency interface{}) bool {
+func setFieldValue(value reflect.Value, elem reflect.Value, i int, dependency interface{}) bool {
 	runeName := []rune(elem.Type().Field(i).Name)
 	exported := unicode.IsUpper(runeName[0])
 	if exported {

autowire.go

@@ -15,6 +15,7 @@ var dependencies map[string]interface{}
 var currentProfile = getProfile()
 var ch = make(chan os.Signal)
 
+// Tag name
 const Tag = "autowire"
 
 func init() {
@@ -36,40 +37,49 @@ func InitProd(initFunc func()) {
 // In order dependencies to be injected the desired struct fields should be marked with
 // autowire tag.
 //
-// Injection of concrete type
+// Concrete type Injection
 //
 // Currently both type of fields exported and unexported are supported.
+//
+// Unexported field
+//
 // Following snippet shows injecting dependencies inside private structure fields using `autowire:""` tag:
 //  type Application struct {
 //      config  *configuration.ApplicationConfig `autowire:""`
 //  }
 //  func (a *Application) SetConfig(config  *configuration.ApplicationConfig)  {
 //      a.config = config
 //  }
-// If we need dependency to be injected into unexported field Set<FieldName> function is required, as show above.
+// If we need given dependency to be injected into unexported field Setter function(Set<FieldName>) is required, as show above.
+// If you have a field called config (lower case, unexported), the setter method should be called SetConfig (upper case, exported), not Setconfig.
+//
+// Exported field
+//
+// The use of upper-case names of the struct fields indicated field is exported.
 //  type Application struct {
 //      Config  *configuration.ApplicationConfig `autowire:""`
 //  }
-// Injection of dependency into exported is supported also and there is no need to provide additional Setter.
+// Dependency injection of exported field is supported with the difference that we don`t provide additional Setter function.
 //
-// Injection of interface
+// Interface Injection
 //
 // Often it`s better to rely on interface instead of concrete type, in order to accomplish this decoupling we specify
 // interfaces as a type of struct fields. The following snippet demonstrate that
 //  type UserService struct {
-//      userRoleRepository UserRoleRepository `autowire:"service/InMemoryUserRoleRepository"`
+//      userRoleRepository UserRoleRepository `autowire:"repository/InMemoryUserRoleRepository"`
 //  }
 //  func (u *UserService) SetUserRoleRepository(userRoleRepository UserRoleRepository) {
 //      u.userRoleRepository = userRoleRepository
 //  }
 // UserRoleRepository is simply an interface and InMemoryUserRoleRepository is a struct, which implements this interface.
 // As it`s done dependency injection on unexported field, providing Setter is required. Just to highlight unexported fields
-// needs Setter while exported not. For more information take a look at example package.
+// needs Setter while exported not. For more information take a look at example#https://github.com/go-autowire/autowire/tree/main/example package.
+// Example:
+//
+//
 func Autowire(v interface{}) {
 	value := reflect.ValueOf(v)
 	switch value.Kind() {
-	case reflect.Invalid:
-		log.Println("invalid reflection type")
 	case reflect.Ptr:
 		structType := getStructPtrFullPath(value)
 		_, ok := dependencies[structType]
@@ -80,6 +90,8 @@ func Autowire(v interface{}) {
 			autowireDependencies(value)
 			dependencies[structType] = v
 		}
+	case reflect.Invalid:
+		log.Panicln("invalid reflection type")
 	default: // reflect.Array, reflect.Struct, reflect.Interface
 		log.Println(value.Type().String() + " value")
 	}
@@ -95,8 +107,6 @@ func Autowired(v interface{}) interface{} {
 	value := reflect.ValueOf(v)
 	var path string
 	switch value.Kind() {
-	case reflect.Invalid:
-		log.Println("invalid")
 	case reflect.Struct:
 		path = getFullPath(value.Type().PkgPath(), value.Type().String())
 	case reflect.Ptr:
@@ -150,18 +160,7 @@ func autowireDependencies(value reflect.Value) {
 				t = reflect.New(elem.Type().Field(i).Type.Elem())
 				dependency, found := dependencies[getStructPtrFullPath(t)]
 				if found {
-					runeName := []rune(elem.Type().Field(i).Name)
-					exported := unicode.IsUpper(runeName[0])
-					if exported {
-						elem.Field(i).Set(reflect.ValueOf(dependency))
-					} else {
-						runeName[0] = unicode.ToUpper(runeName[0])
-						methodName := "Set" + string(runeName)
-						method := value.MethodByName(methodName)
-						if method.IsValid() {
-							method.Call([]reflect.Value{reflect.ValueOf(dependency)})
-						}
-					}
+					setValue(value, elem, i, dependency)
 				}
 			}
 		}
@@ -197,11 +196,11 @@ func findDependency(tagDependencyType string) []interface{} {
 // which implements io.Closer interface will be invoked Call() function, so currently active
 //occupied resources(connections, channels, etc.) could be released.
 func Run(function func()) {
-	defer close()
+	defer closeAll()
 	function()
 }
 
-func close() {
+func closeAll() {
 	log.Println("Closing...")
 	for _, dependency := range dependencies {
 		valueDepend := reflect.ValueOf(dependency)

doc.go

@@ -0,0 +1,15 @@
+// Package Autowire is a framework that makes dependency injection in Golang.
+//
+// Autowire applications use dependency injection framework to eliminate usage
+// of globals without the tedious approach to manually wiring all the
+// dependencies together. Current approach of Autowire framework to accomplish
+// dependency injection is via using struct tags.
+//
+// Basic usage is explained in the package-level example below. If you're new
+// to Autowire, start there!
+//
+// Testing of Autowire Applications
+//
+// To write end-to-end tests of your application, you can use functions provided
+//by atesting package https://godoc.org/github.com/go-autowire/autowire/atesting
+package autowire

example/app/application.go

@@ -17,8 +17,9 @@ type Application struct {
 	userSvc *service.UserService             `autowire:""`
 }
 
+// Start method is starting application
 func (a Application) Start() {
-	log.Println("Config Kind : " + a.config.Kind())
+	log.Println("Config ApiKey : " + a.config.ApiKey()[:3] + "****")
 	userId := "serviceaccount@demo.com"
 	balance, err := a.userSvc.Balance(userId)
 	if err != nil {
@@ -27,14 +28,17 @@ func (a Application) Start() {
 	fmt.Println("Current balance is " + balance.String())
 }
 
+// SetConfig method is a Setter of private field config
 func (a *Application) SetConfig(config *configuration.ApplicationConfig) {
 	a.config = config
 }
 
+// SetUserSvc method is a Setter of private field userSvc
 func (a *Application) SetUserSvc(userSvc *service.UserService) {
 	a.userSvc = userSvc
 }
 
+// UserSvc method is a Getter of private field userSvc
 func (a *Application) UserSvc() *service.UserService {
 	return a.userSvc
 }

example/autowire_test.go

@@ -21,13 +21,12 @@ func (TestPaymentServiceTest) Balance() *big.Float {
 type TestAuditClient struct {
 }
 
-func (TestAuditClient) Send(event string) {
+func (TestAuditClient) Send(_ string) {
 	log.Printf("Test event delivered")
 }
 
 func TestAutowire(t *testing.T) {
-	app := autowire.Autowired(app.Application{}).(*app.Application)
-	app.UserSvc().PaymentSvc = &TestPaymentServiceTest{}
-	atesting.Spies(app, []interface{}{&TestPaymentServiceTest{}, &TestAuditClient{}})
-	app.Start()
+	application := autowire.Autowired(app.Application{}).(*app.Application)
+	atesting.Spies(application, []interface{}{&TestPaymentServiceTest{}, &TestAuditClient{}})
+	application.Start()
 }

example/configuration/application_config.go

@@ -8,14 +8,17 @@ func init() {
 	autowire.Autowire(New("default"))
 }
 
+// A ApplicationConfig represents name struct, which hold application configuration
 type ApplicationConfig struct {
-	kind string
+	apiKey string
 }
 
-func New(kind string) *ApplicationConfig {
-	return &ApplicationConfig{kind: kind}
+// New returns new ApplicationConfig
+func New(apiKey string) *ApplicationConfig {
+	return &ApplicationConfig{apiKey: apiKey}
 }
 
-func (a ApplicationConfig) Kind() string {
-	return a.kind
+// ApiKey is a Setter, which returns apiKey value
+func (a ApplicationConfig) ApiKey() string {
+	return a.apiKey
 }

example/repository/user_repo.go

@@ -6,23 +6,29 @@ func init() {
 	autowire.Autowire(&InMemoryUserRoleRepository{})
 }
 
+// UserRole type
 type UserRole string
 
 const (
+	// OwnerRole
 	OwnerRole UserRole = "owner"
 )
 
+// A String returns UserRole as a string
 func (u UserRole) String() string {
 	return string(u)
 }
 
+// A UserRoleRepository represents interface containing roles related function: GetAllRoles
 type UserRoleRepository interface {
 	GetAllRoles(userId string) ([]UserRole, error)
 }
 
+// A InMemoryUserRoleRepository represents struct, which implements UserRoleRepository interface
 type InMemoryUserRoleRepository struct {
 }
 
+// GetAllRoles returns all roles of the user
 func (i InMemoryUserRoleRepository) GetAllRoles(_ string) ([]UserRole, error) {
 	return []UserRole{OwnerRole}, nil
 }

example/service/audit_client.go

@@ -0,0 +1,21 @@
+package service
+
+import (
+	"log"
+)
+
+// A EventSender represents interface
+type EventSender interface {
+	// Send function is simply dispatching event
+	Send(event string)
+}
+
+// A AuditService represents a named struct
+type AuditService struct {
+	Type string
+}
+
+// A Send is dispatching the event
+func (AuditService) Send(event string) {
+	log.Printf("auditClient Event %s sent", event)
+}