Merge pull request #63 from fabianoflorentino/development

Development to Main

Author: fabianoflorentino

go.mod

@@ -2,4 +2,4 @@ module github.com/fabianoflorentino/aprendago
 
 go 1.23
 
-require gopkg.in/yaml.v2 v2.4.0
+require gopkg.in/yaml.v3 v3.0.1

go.sum

@@ -2,3 +2,5 @@ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/chapter/chapter.go

@@ -10,9 +10,11 @@ import (
 	"github.com/fabianoflorentino/aprendago/internal/aplicacoes"
 	"github.com/fabianoflorentino/aprendago/internal/canais"
 	"github.com/fabianoflorentino/aprendago/internal/concorrencia"
+	"github.com/fabianoflorentino/aprendago/internal/documentacao"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_1"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_10"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_11"
+	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_12"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_2"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_3"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_4"
@@ -62,5 +64,7 @@ func New() []func() {
 		exercicios_ninja_nivel_10.ExerciciosNinjaNivel10,
 		tratamento_de_erro.TratamentoDeErro,
 		exercicios_ninja_nivel_11.ExerciciosNinjaNivel11,
+		documentacao.Documentacao,
+		exercicios_ninja_nivel_12.ExerciciosNinjaNivel12,
 	}
 }

internal/documentacao/overview.yml

@@ -0,0 +1,56 @@
+---
+description:
+  name: "Capítulo 25: Documentação"
+  sections:
+    - title: "Introdução"
+      text: |
+        - Antes de escrever documentação, vamos ver como lê-la. Temos algumas possibilidades:
+            - golang.org → documentação da standard library
+            - godoc.org → documentação da standard library e outros
+            - go doc → comando para ler documentação na linha de comando
+            - godoc → idem acima, para pode-se servir a documentação local via http
+
+    - title: go doc
+      text: |
+        - go help doc
+        - go doc demonstra a documentação de um package, const, func, type, var, método, etc.
+        - go doc aceita zero, um, ou dois argumentos:
+            - zero: demonstra a documentação do package do diretório atual
+            - um: toma argumentos nos padrões abaixo
+                - go doc <pkg>
+                - go doc <sym>[.<method>]
+                - go doc [<pkg>.]<sym>[.<method>]
+                - go doc [<pkg>.][<sym>.]<method>
+            - dois: o primeiro argumento deve ser o nome do package
+                - go doc <pkg> <sym>[.<method>]
+
+    - title: godoc
+      text: |
+        - godoc extrai e gera documentação de programas em Go. Funciona de duas maneiras:
+          - Sem o flag http é um comando normal, mostra a documentação no stdout e é isso aí. Pode conter o flag src, que mostra o código fonte.
+          - Com o flag http roda um servidor web local e mostra a documentação como página web.
+        - Exemplo: godoc -http=:8080 → http://localhost:8080/
+
+    - title: https://pkg.go.dev/
+      text: |
+        - Documentação da standard library e outros
+        - Como colocar a documentação do seu package no godoc.org
+        - refresh, delete
+
+    - title: Escrevendo documentação
+      text: |
+        - Documentação é uma parte extremamente importante de fazer com que software seja acessível e sustentável.
+        - Documentação deve ser bem escrita e correta, mas tambem fácil de escrever e manter.
+        - Deve ser acoplada com o código e evoluir junto com este. Quanto mais fácil for para os programadores criarem boa documentação... melhor fica pra todos os envolvidos.
+        - godoc:
+            - Analisa código fonte em Go, incluindo comentários, e gera documentação em HTML ou texto
+            - O resultado é uma documentação firmemente atrelada ao código que documenta.
+            - Por exemplo, na interface web de godoc pode-se navegar da documentação à implementação de um código com apenas um clique.
+            - https://blog.golang.org/godoc-documenting-go-code
+        - Na prática:
+            - Para documentar um tipo, uma variável, uma constante, ou um pacote, escreva um comentário imediatamente antes de sua declaração, sem linhas em branco
+            - Comece a frase com o nome do elemento. No caso de pacotes, a primeira linha aparece no "package list."
+            - Caso esteja escrevendo bastante documentação, utilize um arquivo doc.go. Exemplo: package fmt.
+        - A melhor parte dessa abordagem minimalista é que é super fácil de usar. Como resultado, muita coisa em Go, incluindo toda a standard library, já segue estas convenções.
+        - Outro exemplo: errors package.
+        - Código: https://github.com/ellenkorbes/aprendago/tree/master/c%C3%B3digo/25_escrevendo-documentacao

internal/documentacao/topics.go

@@ -0,0 +1,48 @@
+package documentacao
+
+import (
+	"fmt"
+
+	"github.com/fabianoflorentino/aprendago/pkg/format"
+)
+
+const (
+	rootDir = "internal/documentacao"
+)
+
+func Documentacao() {
+	fmt.Printf("\n\nCapítulo 25: Documentação\n")
+
+	executeSections("Introdução")
+	executeSections("go doc")
+	executeSections("godoc")
+	executeSections("https://pkg.go.dev/")
+	executeSections("Escrevendo documentação")
+}
+
+func MenuDocumentacao([]string) []format.MenuOptions {
+	return []format.MenuOptions{
+		{Options: "--introducao", ExecFunc: func() { executeSections("Introdução") }},
+		{Options: "--go-doc", ExecFunc: func() { executeSections("go doc") }},
+		{Options: "--godoc", ExecFunc: func() { executeSections("godoc") }},
+		{Options: "--pkg-go-dev", ExecFunc: func() { executeSections("https://pkg.go.dev/") }},
+		{Options: "--escrevendo-documentacao", ExecFunc: func() { executeSections("Escrevendo documentação") }},
+	}
+}
+
+func HelpMeDocumentacao() {
+	hlp := []format.HelpMe{
+		{Flag: "--introducao", Description: "Introdução"},
+		{Flag: "--go-doc", Description: "go doc"},
+		{Flag: "--godoc", Description: "godoc"},
+		{Flag: "--pkg-go-dev", Description: "https://pkg.go.dev/"},
+		{Flag: "--escrevendo-documentacao", Description: "Escrevendo documentação"},
+	}
+
+	fmt.Printf("\nCapítulo 25: Documentação")
+	format.PrintHelpMe(hlp)
+}
+
+func executeSections(section string) {
+	format.FormatSection(rootDir, section)
+}

internal/exercicios_ninja_nivel_12/overview.yml

@@ -0,0 +1,28 @@
+---
+description:
+  name: "Capítulo 26: Exercícios ninja nível 12"
+  sections:
+    - title: "Na prática: Exercício #1"
+      text: |
+        - Crie um package "cachorro".
+            - Este package deverá exportar uma função Idade, que toma como parâmetro um número de anos e retorna a idade equivalente em anos caninos. (1 ano humano → 7 anos caninos)
+            - Documente seu código com comentários, e utilize a função Idade na sua função main.
+        - Rode seu programa para verificar se ele funciona.
+        - Rode um local server com godoc e leia sua documentação.
+        - Solução: https://github.com/ellenkorbes/aprendago/tree/master/c%C3%B3digo/26_exercicios-ninja-12/01_cachorro
+
+    - title: "Na prática: Exercício #2"
+      text: |
+        - Coloque seu código no GitHub.
+        - Faça sua documentação aparecer em godoc.org, e tire um screenshot.
+        - Delete seu código do GitHub.
+        - Faça um refresh em godoc.org e veja se seu código sumiu.
+        - Compartilhe seu exercício aqui: https://github.com/ellenkorbes/aprendago/issues/79
+
+    - title: "Na prática: Exercício #3"
+      text: |
+        - Use godoc na linha de comando para ver a documentação sobre:
+          - fmt
+          - fmt Print
+          - strings
+          - strconv

internal/exercicios_ninja_nivel_12/resolution_exercises.go

@@ -0,0 +1,27 @@
+package exercicios_ninja_nivel_12
+
+import "fmt"
+
+// ResolucaoNaPraticaExercicio1 calculates and prints the age of a dog in dog years
+// based on a given human age. The age is hardcoded as 3 years in this example.
+func ResolucaoNaPraticaExercicio1() {
+	idade := 3
+	idadeCachorro := idadeDeCachorro(idade)
+
+	fmt.Printf("A idade do cachorro em anos humanos é: %d", idadeCachorro)
+}
+
+func ResolucaoNaPraticaExercicio2() {
+	fmt.Printf("Não há resolução para este exercício.")
+}
+
+func ResolucaoNaPraticaExercicio3() {
+	fmt.Printf("Não há resolução para este exercício.")
+}
+
+// idadeDeCachorro converts a dog's age from human years to dog years.
+// It takes an integer representing the dog's age in human years and returns
+// the equivalent age in dog years, calculated by multiplying the input by 7.
+func idadeDeCachorro(idade int) int {
+	return idade * 7
+}

internal/exercicios_ninja_nivel_12/topics.go

@@ -0,0 +1,50 @@
+package exercicios_ninja_nivel_12
+
+import (
+	"fmt"
+
+	"github.com/fabianoflorentino/aprendago/pkg/format"
+)
+
+// rootDir represents the relative path to the directory containing
+// the exercises for level 11 of the ninja training program.
+const (
+	rootDir = "internal/exercicios_ninja_nivel_12"
+)
+
+func ExerciciosNinjaNivel12() {
+	fmt.Printf("\n\nCapítulo 26: Exercicios: Ninja Nível 12\n")
+
+	executeSection("Na prática: Exercício #1")
+	executeSection("Na prática: Exercício #2")
+	executeSection("Na prática: Exercício #3")
+}
+
+func MenuExerciciosNinjaNivel12([]string) []format.MenuOptions {
+	return []format.MenuOptions{
+		{Options: "--na-pratica-exercicio-1 --nivel-12", ExecFunc: func() { executeSection("Na prática: Exercício #1") }},
+		{Options: "--na-pratica-exercicio-1 --nivel-12 --resolucao", ExecFunc: func() { ResolucaoNaPraticaExercicio1() }},
+		{Options: "--na-pratica-exercicio-2 --nivel-12", ExecFunc: func() { executeSection("Na prática: Exercício #2") }},
+		{Options: "--na-pratica-exercicio-2 --nivel-12 --resolucao", ExecFunc: func() { ResolucaoNaPraticaExercicio2() }},
+		{Options: "--na-pratica-exercicio-3 --nivel-12", ExecFunc: func() { executeSection("Na prática: Exercício #3") }},
+		{Options: "--na-pratica-exercicio-3 --nivel-12 --resolucao", ExecFunc: func() { ResolucaoNaPraticaExercicio3() }},
+	}
+}
+
+func HelpMeExerciciosNinjaNivel12() {
+	hlp := []format.HelpMe{
+		{Flag: "--na-pratica-exercicio-1 --nivel-12", Description: "Apresenta o primeiro exercício prático do curso.", Width: 0},
+		{Flag: "--na-pratica-exercicio-1 --nivel-12 --resolucao", Description: "Exibe a resolução do primeiro exercício prático.", Width: 0},
+		{Flag: "--na-pratica-exercicio-2 --nivel-12", Description: "Apresenta o segundo exercício prático do curso.", Width: 0},
+		{Flag: "--na-pratica-exercicio-2 --nivel-12 --resolucao", Description: "Exibe a resolução do segundo exercício prático.", Width: 0},
+		{Flag: "--na-pratica-exercicio-3 --nivel-12", Description: "Apresenta o terceiro exercício prático do curso.", Width: 0},
+		{Flag: "--na-pratica-exercicio-3 --nivel-12 --resolucao", Description: "Exibe a resolução do terceiro exercício prático.", Width: 0},
+	}
+
+	fmt.Printf("\nCapítulo 26: Exercicios Ninja Nível 12\n")
+	format.PrintHelpMe(hlp)
+}
+
+func executeSection(section string) {
+	format.FormatSection(rootDir, section)
+}

internal/menu/capitulo_options.go

@@ -9,9 +9,11 @@ import (
 	"github.com/fabianoflorentino/aprendago/internal/aplicacoes"
 	"github.com/fabianoflorentino/aprendago/internal/canais"
 	"github.com/fabianoflorentino/aprendago/internal/concorrencia"
+	"github.com/fabianoflorentino/aprendago/internal/documentacao"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_1"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_10"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_11"
+	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_12"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_2"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_3"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_4"
@@ -60,6 +62,8 @@ func MenuCapituloOptions([]string) []format.MenuOptions {
 		{Options: "--cap=22 --topics", ExecFunc: func() { exercicios_ninja_nivel_10.HelpMeExerciciosNinjaNivel10() }},
 		{Options: "--cap=23 --topics", ExecFunc: func() { tratamento_de_erro.HelpMeTratamentoDeErro() }},
 		{Options: "--cap=24 --topics", ExecFunc: func() { exercicios_ninja_nivel_11.HelpMeExerciciosNinjaNivel11() }},
+		{Options: "--cap=25 --topics", ExecFunc: func() { documentacao.HelpMeDocumentacao() }},
+		{Options: "--cap=26 --topics", ExecFunc: func() { exercicios_ninja_nivel_12.HelpMeExerciciosNinjaNivel12() }},
 	}
 }
 
@@ -94,6 +98,8 @@ func HelpMeCapituloOptions() {
 		{Flag: "--cap=22 --topics", Description: "Exercícios Ninja: Nível 10"},
 		{Flag: "--cap=23 --topics", Description: "Tratamento de Erro"},
 		{Flag: "--cap=24 --topics", Description: "Exercícios Ninja: Nível 11"},
+		{Flag: "--cap=25 --topics", Description: "Documentação"},
+		{Flag: "--cap=26 --topics", Description: "Exercícios Ninja: Nível 12"},
 	}
 
 	fmt.Println("Capítulos do Curso")

internal/menu/capitulo_outline.go

@@ -10,8 +10,10 @@ import (
 	"github.com/fabianoflorentino/aprendago/internal/aplicacoes"
 	"github.com/fabianoflorentino/aprendago/internal/canais"
 	"github.com/fabianoflorentino/aprendago/internal/concorrencia"
+	"github.com/fabianoflorentino/aprendago/internal/documentacao"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_10"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_11"
+	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_12"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_2"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_3"
 	"github.com/fabianoflorentino/aprendago/internal/exercicios_ninja_nivel_4"
@@ -62,6 +64,8 @@ func MenuCapituloOutline([]string) []format.MenuOptions {
 		{Options: "--cap=22 --overview", ExecFunc: func() { exercicios_ninja_nivel_10.ExerciciosNinjaNivel10() }},
 		{Options: "--cap=23 --overview", ExecFunc: func() { tratamento_de_erro.TratamentoDeErro() }},
 		{Options: "--cap=24 --overview", ExecFunc: func() { exercicios_ninja_nivel_11.ExerciciosNinjaNivel11() }},
+		{Options: "--cap=25 --overview", ExecFunc: func() { documentacao.Documentacao() }},
+		{Options: "--cap=26 --overview", ExecFunc: func() { exercicios_ninja_nivel_12.ExerciciosNinjaNivel12() }},
 	}
 }
 
@@ -93,6 +97,9 @@ func HelpMeCapituloOutline() {
 		{Flag: "--cap=21 --overview", Description: "Canais"},
 		{Flag: "--cap=22 --overview", Description: "Exercícios Ninja Nível 10"},
 		{Flag: "--cap=23 --overview", Description: "Tratamento de Erro"},
+		{Flag: "--cap=24 --overview", Description: "Exercícios Ninja Nível 11"},
+		{Flag: "--cap=25 --overview", Description: "Documentação"},
+		{Flag: "--cap=26 --overview", Description: "Exercícios Ninja Nível 12"},
 	}
 
 	fmt.Printf("\nOutline do Curso por Capítulo\n")