1. 05 Oct, 2016 1 commit
    • Joe Tsai's avatar
      cmd/doc: ensure summaries truly are only one line · 84743c34
      Joe Tsai authored
      The documentation for doc says:
      > Doc prints the documentation comments associated with the item identified by its
      > arguments (a package, const, func, type, var, or method) followed by a one-line
      > summary of each of the first-level items "under" that item (package-level
      > declarations for a package, methods for a type, etc.).
      
      Certain variables (and constants, functions, and types) have value specifications
      that are multiple lines long. Prior to this change, doc would print out all of the
      lines necessary to display the value. This is inconsistent with the documented
      behavior, which guarantees a one-line summary for all first-level items.
      We fix this here by writing a general oneLineNode method that always returns
      a one-line summary (guaranteed!) of any input node.
      
      Packages like image/color/palette and unicode now become much
      more readable since large slices are now a single line.
      
      $ go doc image/color/palette
      <<<
      // Before:
      var Plan9 = []color.Color{
      	color.RGBA{0x00, 0x00, 0x00, 0xff},
      	color.RGBA{0x00, 0x00, 0x44, 0xff},
      	color.RGBA{0x00, 0x00, 0x88, 0xff},
      	... // Hundreds of more lines!
      }
      var WebSafe = []color.Color{
      	color.RGBA{0x00, 0x00, 0x00, 0xff},
      	color.RGBA{0x00, 0x00, 0x33, 0xff},
      	color.RGBA{0x00, 0x00, 0x66, 0xff},
      	... // Hundreds of more lines!
      }
      
      // After:
      var Plan9 = []color.Color{ ... }
      var WebSafe = []color.Color{ ... }
      >>>
      
      In order to test this, I ran `go doc` and `go doc -u` on all of the
      standard library packages and diff'd the output with and without the
      change to ensure that all differences were intended.
      
      Fixes #13072
      
      Change-Id: Ida10b7796b7e4e174a929b55c60813a9eb7158fe
      Reviewed-on: https://go-review.googlesource.com/25420
      Run-TryBot: Joe Tsai <thebrokentoaster@gmail.com>
      TryBot-Result: Gobot Gobot <gobot@golang.org>
      Reviewed-by: default avatarRob Pike <r@golang.org>
      84743c34
  2. 04 Oct, 2016 27 commits
  3. 03 Oct, 2016 12 commits