suggested change to template.Funcs docstring

[Rory Campbell-Lange]

The docstring for [html|text]/template.Funcs is as follows

package template // import "html/template"

func (t *Template) Funcs(funcMap FuncMap) *Template
Funcs adds the elements of the argument map to the template's function map.
It must be called before the template is parsed. It panics if a value in
the map is not a function with appropriate return type. However, it is
legal to overwrite elements of the map. The return value is the template,
so calls can be chained.

(The html version has the addition of "However"!).

It wasn't obvious to me that to "overwrite elements of the map" one could call
Funcs with a funcMap of just those funcs that should be replaced, as shown in
https://go.dev/play/p/LWRmEL9XZce, rather than having to re-add all the funcs.

Although this might be more obvious to experienced gophers, I suggest the
following addition to the docs:

...it is legal to overwrite elements of the map. For example, a func
registered with the name "x" before a template t is parsed might be
replaced after parsing the template as follows:

t.Funcs(template.FuncMap{"x": strings.ToUpper})

The return value...

Thanks
Rory

[Ian Lance Taylor]

Another approach would be to add an example. Want to send a patch?

Ian

[Rory Campbell-Lange]

On 27/02/25, Ian Lance Taylor (ia...@golang.org) wrote:
> On Thu, Feb 27, 2025 at 1:04 PM Rory Campbell-Lange
> <ro...@campbell-lange.net> wrote:

...

> > It wasn't obvious to me that to "overwrite elements of the map" one could call
> > Funcs with a funcMap of just those funcs that should be replaced

> > https://go.dev/play/p/LWRmEL9XZce, rather than having to re-add all the funcs.
> >
> > Although this might be more obvious to experienced gophers, I suggest the
> > following addition to the docs:
...

> Another approach would be to add an example. Want to send a patch?

I'll give that a go.

[Rory Campbell-Lange]

Might this be appropriate as an example?

https://github.com/rorycl/go/commit/15e069e9474a256988db88832177aaff22421eaa

[Ian Lance Taylor]

On Fri, Feb 28, 2025 at 12:19 PM Rory Campbell-Lange

<ro...@campbell-lange.net> wrote:
>
> On 27/02/25, Rory Campbell-Lange (ro...@campbell-lange.net) wrote:
> > On 27/02/25, Ian Lance Taylor (ia...@golang.org) wrote:
> > > On Thu, Feb 27, 2025 at 1:04 PM Rory Campbell-Lange
> > > <ro...@campbell-lange.net> wrote:
> > ...
> > > > It wasn't obvious to me that to "overwrite elements of the map" one could call
> > > > Funcs with a funcMap of just those funcs that should be replaced
> > > > https://go.dev/play/p/LWRmEL9XZce, rather than having to re-add all the funcs.
> > > >
> > > > Although this might be more obvious to experienced gophers, I suggest the
> > > > following addition to the docs:
> > ...
> > > Another approach would be to add an example. Want to send a patch?
>
> Might this be appropriate as an example?
>
> https://github.com/rorycl/go/commit/15e069e9474a256988db88832177aaff22421eaa

Looks reasonable, thanks.

Ian