Standard format for writing a reference manual in code

Help and Feedback Scripting Support
#1

I have an object with a variety of methods that I want to explain at the top of the script. Is there a standard format for doing that? I don’t want to use luadoc because it spreads out the documentation and makes the code harder to read. Here are a couple of formats as examples.

#1 Javadoc-ish:

--[[
A group of fixtures that you can perform effects on.

@param <String> name The name of the group
@param <varargs> ... The fixtures that belong in the group
Group.new(name, ...)

@return <String> The name of the group
Group:GetName()

@param <String> name The desired name of the group
Group:SetName(name)
--]]

#2 Lists and sublists

--[[
A group of fixtures that you can perform effects on.

Group.new(name, ...)
	Params
		<String> name The name of the group
		<varags> ... The fixtures that belong in the group

Group:GetName()
	Return
		<String> The name of the group

Group:SetName(name)
	Params
		<String> name The desired name of the group
--]]
#2

I would say the #2 is better, since it looks much cleaner for me.

1 Like