From 02ef8fa5ddb8111aa8752ffb8267e67c4e209649 Mon Sep 17 00:00:00 2001 From: Steve Traut Date: Mon, 1 Mar 2021 10:42:43 -0500 Subject: _content/doc: fix module and tutorial bugs and clean up flow For golang/go#44241 - Fix issues 2, 3, 8, 16, 17, 18 from golang/go#44241 Other changes in multiple topics: - In markdown, replace HTML anchor tags with {#anchor} tags. - In a few places, add content to clarify that module path must be a location from which the module can be downloaded. - Where it was missing, add example.com domain to example module paths. Hopefully, this will reinforce the idea that the module path should typically include a domain. Docs will use something that looks like a domain name for module path. - Add more cross-references from tutorial to references for packages and commands. - Rewrite a few links so that they include the topic title, rather than simply inline text. Left those links whose destinations are references -- the item's name seems to suggest that a reference is at the destination. - Remove domain name from golang.org doc links, leaving root directory. Such as /cmd/go/* or /doc/modules/* - Add path up to root for all links in the same domain. Some were linking by file name only. - Change standard library links from golang.org to pkg.go.dev. Changes in the module tutorial: - Add text to help clarify that there should be a hello and greetings directory as siblings in their directory hierarchy. Some users thought one should be subordinate to the other. - Where needed, reorder steps so that `go mod init` is run before code is added. This is intended to reinforce the importance of the module's presence. - In require/replace steps, have the user use `go mod edit` rather than editing the go.mod file in an editor. The tools are more likely to yield a functioning result. - Where possible/appropriate, change module directive link destinations from "Modules reference" to go.mod reference. - Change "run the code" steps so that they all use `go run .` rather than `go build` or `go run `. This removes the impedance of explanation and more commands, while moving the explanation of `go build` and `go install` to a separate topic where they share a clearer context. - Add a "Conclusion" topic with a few links. The tutorial ended rather abruptly before. - Minor edits to remove some redundant language. Change-Id: I93055035d73c362ba73edea458fc53bc45e66512 Reviewed-on: https://go-review.googlesource.com/c/website/+/297531 Trust: Steve Traut Run-TryBot: Steve Traut TryBot-Result: Go Bot Reviewed-by: Jay Conrod --- _content/doc/tutorial/create-module.html | 81 ++++++++++++++++---------------- 1 file changed, 40 insertions(+), 41 deletions(-) (limited to '_content/doc/tutorial/create-module.html') diff --git a/_content/doc/tutorial/create-module.html b/_content/doc/tutorial/create-module.html index cf6558c0..3dbe35f4 100644 --- a/_content/doc/tutorial/create-module.html +++ b/_content/doc/tutorial/create-module.html @@ -6,8 +6,8 @@

This is the first part of a tutorial that introduces a few fundamental features of the Go language. If you're just getting started with Go, be sure - to take a look at the - getting started tutorial, which introduces + to take a look at + Tutorial: Get started with Go, which introduces the go command, Go modules, and very simple Go code.

@@ -28,36 +28,36 @@ another module.
  • - Call your code from another module -- + Call your code from another module -- Import and use your new module.
  • - Return and handle an error -- Add simple + Return and handle an error -- Add simple error handling.
  • - Return a random greeting -- Handle data + Return a random greeting -- Handle data in slices (Go's dynamically-sized arrays).
  • - Return greetings for multiple people -- Store key/value pairs in a map.
  • - Add a test -- Use Go's built-in unit testing + Add a test -- Use Go's built-in unit testing features to test your code.
  • - Compile and install the application -- + Compile and install the application -- Compile and install your code locally.

    • Prerequisites

    @@ -81,18 +81,18 @@

    Start a module that others can use

    - Start by creating a - Go module. In a + Start by creating a Go module. In a module, you collect one or more related packages for a discrete and useful set of functions. For example, you might create a module with packages that have functions for doing financial analysis so that others writing financial - applications can use your work. + applications can use your work. For more about developing modules, see + Developing and publishing modules.

    Go code is grouped into packages, and packages are grouped into modules. Your - package's module specifies the context Go needs to run the code, including the - Go version the code is written for and the set of other modules it requires. + module specifies dependencies needed to run your code, including the Go + version and the set of other modules it requires.

    @@ -127,7 +127,6 @@ cd %HOMEPATH%

  • Create a greetings directory for your Go module source code. - This is where you'll write your module code.

    For example, from your home directory use the following commands: @@ -143,16 +142,15 @@ cd greetings

  • Start your module using the go mod init command - to create a go.mod file. + >.

    - Run the go mod init command, giving it the path of the module - your code will be in. Here, use example.com/greetings for the - module path -- in production code, this would be the URL from which your - module can be downloaded. + Run the go mod init command, giving it your module path -- + here, use example.com/greetings. If you publish a module, + this must be a path from which your module can be downloaded by + Go tools. That would be your code's repository. 

    @@ -162,13 +160,12 @@ go: creating new go.mod: module example.com/greetings
     >
 
     
    
-      The go mod init command creates a go.mod file that identifies
-      your code as a module that might be used from other code. The file you
-      just created includes only the name of your module and the Go version your
-      code supports. But as you add dependencies -- meaning packages from other
-      modules -- the go.mod file will list the specific module versions to use.
-      This keeps builds reproducible and gives you direct control over which
-      module versions to use.
+      The go mod init command creates a go.mod file to track your
+      code's dependencies. So far, the file includes only the name of your
+      module and the Go version your code supports. But as you add dependencies,
+      the go.mod file will list the versions your code depends on. This keeps
+      builds reproducible and gives you direct control over which module
+      versions to use.
    • @@ -212,10 +209,12 @@ func Hello(name string) string { Implement a Hello function to return the greeting.

    This function takes a name parameter whose type is - string, and returns a string. In Go, a - function whose name starts with a capital letter can be called by a - function not in the same package. This is known in Go as an - exported name. + string. The function also returns a string. + In Go, a function whose name starts with a capital letter can be + called by a function not in the same package. This is known in Go as + an exported name. For more about exported names, see + Exported names in the + Go tour.

    @@ -236,11 +235,12 @@ message = fmt.Sprintf("Hi, %v. Welcome!", name)
  • - Use the fmt package's Sprintf function to - create a greeting message. The first argument is a format string, and - Sprintf substitutes the name parameter's value - for the %v format verb. Inserting the value of the - name parameter completes the greeting text. + Use the fmt package's + Sprintf function to create a greeting message. The + first argument is a format string, and Sprintf substitutes + the name parameter's value for the %v format + verb. Inserting the value of the name parameter completes + the greeting text.
  • Return the formatted greeting text to the caller.
    • @@ -248,12 +248,11 @@ message = fmt.Sprintf("Hi, %v. Welcome!", name)

    - In the next step, you'll call this - function from another module. + In the next step, you'll call this function from another module.

    - Call your code from another module >

    -- cgit v1.3