search

minetest / minetest_docs

Minetest Engine documentation (Work in progress. Meanwhile, please refer to lua_api.txt and dev.minetest.net)
Other
22 stars 13 forks source link

Template is overly verbose and at times misleading #39

Open appgurueu opened 2 years ago

appgurueu commented 2 years ago
  1. Why all the {type-<typename>} macros rather than just <typename>?
  2. Why are properties documented as Vehicle.property? This implies that they were "class variables" (static in Java) rather than per-instance fields. I suggest documenting them just as property to reduce redundancy. Why do fields not use the table format used for arguments & returns?
  3. "Usage" is redundant with arguments + returns
  4. Methods shouldn't be referred to as Vehicle:method as this may be confused with the class:new syntax often used for Lua OOP which MT doesn't use. Vehicle shouldn't be littered all over the document.
  5. Method names should be in monospace.
  6. Table styling should not be all over the place.
GreenXenith commented 2 years ago

Why all the {type-<typename>} macros rather than just <typename>?

The type name alone is ambiguous and not explicit. Macros should be prefixed for categorization anyway.

"Usage" is redundant with arguments + returns

Clarity. It is easier to see a line of code than construct it in your head using some tables.

Table styling should not be all over the place.

If it can be global, sure.

[2, 4, 5]

The template is not set in stone yet and still needs iterating. Further discussion should probably be in docs channels.