minetest_docs icon indicating copy to clipboard operation
minetest_docs copied to clipboard

Improve template (axes footer)

Open appgurueu opened this issue 3 years ago • 1 comments

The current template is overly verbose (see https://github.com/minetest/minetest_docs/issues/39). This PR attempts to alleviate that. Please discuss.

appgurueu avatar Sep 16 '22 12:09 appgurueu

I've switched methods to :method(...) for headers. Two things I don't like about this:

  • Stuffing the arguments in the header is redundant. They should probably go.
  • Similarly, stuffing the returns in the header is hardly possible (a, b = :method(c, d) is invalid Lua and looks odd; omitting the self doesn't really work if you want to put something in front of the colon).

I'd be fine with switching to :method or .method, but not with removing the : and . as is the case with the current template. Colon vs. dot is very important here since both are possible and used by Minetest (e.g. auth handler doesn't need self and uses dot). We also want to remind newcomers or people coming from other programming languages that they have to pass self as an implicit first argument (without writing it down in the argument table). Simply having methods be in a subsection "methods" is not explicit enough.

appgurueu avatar Sep 16 '22 12:09 appgurueu