time: Improving time layout docs

[jeremyheiler]

I just spent some time figuring out how time layouts work. It didn't click for me until I read a post on StackOverflow that essentially copied this block of code below into an answer.

    61  const (
    62      _                        = iota
    63      stdLongMonth             = iota + stdNeedDate  // "January"
    64      stdMonth                                       // "Jan"
    65      stdNumMonth                                    // "1"
    66      stdZeroMonth                                   // "01"
    67      stdLongWeekDay                                 // "Monday"
    68      stdWeekDay                                     // "Mon"
    69      stdDay                                         // "2"
    70      stdUnderDay                                    // "_2"
    71      stdZeroDay                                     // "02"
    72      stdHour                  = iota + stdNeedClock // "15"
    73      stdHour12                                      // "3"
    74      stdZeroHour12                                  // "03"
    75      stdMinute                                      // "4"
    76      stdZeroMinute                                  // "04"
    77      stdSecond                                      // "5"
    78      stdZeroSecond                                  // "05"
    79      stdLongYear              = iota + stdNeedDate  // "2006"
    80      stdYear                                        // "06"
    81      stdPM                    = iota + stdNeedClock // "PM"
    82      stdpm                                          // "pm"
    83      stdTZ                    = iota                // "MST"
    84      stdISO8601TZ                                   // "Z0700"  // prints Z for UTC
    85      stdISO8601SecondsTZ                            // "Z070000"
    86      stdISO8601ColonTZ                              // "Z07:00" // prints Z for UTC
    87      stdISO8601ColonSecondsTZ                       // "Z07:00:00"
    88      stdNumTZ                                       // "-0700"  // always numeric
    89      stdNumSecondsTz                                // "-070000"
    90      stdNumShortTZ                                  // "-07"    // always numeric
    91      stdNumColonTZ                                  // "-07:00" // always numeric
    92      stdNumColonSecondsTZ                           // "-07:00:00"
    93      stdFracSecond0                                 // ".0", ".00", ... , trailing zeros included
    94      stdFracSecond9                                 // ".9", ".99", ..., trailing zeros omitted
    95  
    96      stdNeedDate  = 1 << 8             // need month, day, year
    97      stdNeedClock = 2 << 8             // need hour, minute, second
    98      stdArgShift  = 16                 // extra argument in high bits, above low stdArgShift
    99      stdMask      = 1<<stdArgShift - 1 // mask out argument
   100  )

(from http://golang.org/src/time/format.go)

Can the docs show this block fo code, or display a lookup table? After chatting on IRC, it sounded like questions relating to how layouts work appear often. I feel like this would make the docs clearer.

[robpike]

I believe the new (1.6) docs (http://tip.golang.org/pkg/time/#pkg-constants and http://tip.golang.org/pkg/time/#Parse) and example (http://tip.golang.org/pkg/time/#example_Time_Format) example do a much better job than the old docs.

If there are details missing that are covered by the table above, please say so.

[jeremyheiler]

Thanks