How to Contribute

Basics

Everyone is welcome to contribute to this API documentation.  We have 3 types of user roles here.

  • Contributor – allowed to edit all pages and submit for review
  • Author – allowed to publish all pages and accept reviews
  • Editor – allowed to change the menus, appearance and theme settings

Every new user will start as a contributor. This is necessary to prevent someone from trolling us and to ensure we produce quality content. We have a few basic requirements we’d like you to meet.

  • Knowledge of Don’t Starve and/or Don’t Starve Together
  • Experience in LUA
  • Will to write understandable and structured content
  • Indestructive workflow (do not simply delete or alter existing content)

The registration link is located in the sidebar. After your registration you will receive an email with your login credentials. You can start editing immediately.

Discussions

When editing a page, you can leave editorial comments below the editor frame. This serves as a way of communication between contributors, and makes improving a page easier. As an contributor, you get notified of comments on your pages, authors and higher get notified of any comment. It is good to question content that sounds dubious that way, but trivial things like broken formatting, typos or complicated text passages should be changed directly.

For questions that are not related to any existing page you should use the chat function on the dashboard within WordPress.

Everything else should be discussed or referenced in this thread in the KLEI forums.

Formatting

Page structure

You cannot add pages to the menus top level. Every page must be properly marked as child of another page. All top level pages appear in the menu. The menu widget will display all child pages recursively as a dropdown. Most of the pages that you will need already exist as drafts. Use these pages or create a new one and mark it as child page of some other page. You can display all child pages of the current page with this shortcode.

Contributors should submit their changes for review, authors should publish them.

Header Structure

Headers of level <h1> should absolutely not be used. For headers of sections containing extended descriptions about tables, use the foo(argname1, arg2) definition in the source, which would make it much easier to understand. Commonly-known magic words like "prefab", fn are also allowed if they look cleverer.

Arrangement of header levels can go in a variety of ways. Usually it goes like this:

  • foo(bar)
    • local addFoo() Only if it is worthy to explain, like when you can’t get the above text round.
  • bar(baz)
  • Common Local Functions
    • raw(foo, bar, baz) Only if it is really common throughout the current class/file

For interfaces that exposes a special but more useful set of APIs, like ModUtil, that set would be documented and the actual implementation would be put in some pages like PAGENAME Internals (PAGENAME/internal).

Tables

Every API documentation needs to display fields and methods. We use the TablePress plugin to create nicely formatted lists. You can create them in the TablePress tab. The naming scheme for a table id is CLASSNAME_fields / CLASSNAME_methods . Please stick to a proper naming scheme. It makes life easier for all of us. You can simply copy an existing table to make it easy. If there is an existing table which suits your needs, use it instead of creating a new one. Here are two examples.

Demo Fields

TypeNameDescription
numberindexLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
booleanisActiveLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam

Demo Methods

NameParameterReturnsDescription
function1arg1 = 3, arg2 = "placeholderstr"nilLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
function2arg1nilLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam

Consider adding anchor links back to chapters of the page if you have additional information for them. Adding something like <code>= foo</code> means some non-nil default values for the function / method, and <code>: Class[, type, type2]</code> means the code is meant for the argument of this type(s) and/or Class(es).

Lua

You most likely need to write some Lua code at some point. Just use the pre tag like this. You can also highlight some lines to refer to. Just put “mark:7,9-10” inside the class attribute.

Here is what it can look like.

You should make the title a relative pathname to either data/scripts/ or mods/.