Document the .Sub, .After and other calculation functions that can be used for time

[kaushalmodi]

• https://godoc.org/time#Time
• https://discourse.gohugo.io/t/convert-a-string-to-a-time-datetime/11515/3
• https://discourse.gohugo.io/t/parsing-dates-in-templates/603/15
• https://gohugohq.com/howto/compare-date-strings-in-hugo/#calculations

[moorereason]

Agreed. These are not really functions. They are methods on time.Time objects. Consider the fact that we need to document the type not individual functions.

[kaushalmodi]

These are not really functions.

TIL that Go distinguishes methods from functions.. I googled a bit, but I still couldn't quite grasp the difference.. the resources I referred went into other Go lang lingo like "receivers" and stuff. If you don't mind explaining, what would be a 1-2 liner difference between a method and function?

From what I see.. the time.Time methods ship with the Go lang itself? whereas the functions are part of, and specific to Hugo?

Consider the fact that we need to document the type not individual functions.

I didn't quite understand that. Do you mean that we just list all the methods available for variables of type time.Time, and then link to the godoc.org documentation?

[moorereason]

what would be a 1-2 liner difference between a method and function?

Methods are tied to a specific type (or an instance of an object in OOP). Functions are stand-alone.

For an example function, look at time.Parse(). Parse stands alone and simply operates on the parameters you pass it. It, in turn, gives you a Time object back.

By contrast, that Time type has many methods hanging off of it, such as Time.Day(). You don't pass it parameters like you did to Parse--the Time type has everything it needs already and just returns the integer for the day defined within it.

From what I see.. the time.Time methods ship with the Go lang itself? whereas the functions are part of, and specific to Hugo?

Yes. We use the Go time.Time type, so its properties and methods are exposed to the user in the templates. Hugo has its own types as well, such as Pages, Images, etc.

Almost all of the functions in Hugo templates are functions we created.

Do you mean that we just list all the methods available for variables of type time.Time, and then link to the godoc.org documentation?

Not exactly. I prefer to have our docs be self-contained, so I'd rather not link to the godocs. They're meant for a different audience, anyway.

I envisioned a Time page similar to our Git Variables page. We would move Time methods (like .Format, .AddDate, and .Unix) to that page where they belong, and add anything else from the time.Time type that seems relevant. Then from functions such as time, now, and dateFormat, we link to the Time Variables page for additional info.

[moorereason]

Related to #105.

[bep]

We have an outstanding issue getting a good separation between methods and funcs in the docs. We have used the ".Something" to indicate a method. The main point being that the functions are "standalone" and the methods do not make sense without the receiver.

[moorereason]

@bep,
My argument is that we document the main types (with their properties & methods) separate from the functions. As you say, tie the methods to their receiver. We already do that for some types, but not all.

Are you and I agreeing here? If not, where do we differ?

[bep]

Are you and I agreeing here? If not, where do we differ?

We agree.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If you still think this is important, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.