diff --git a/utils/locale_builder.lua b/utils/locale_builder.lua
index 2b33ced8..2a6fe466 100644
--- a/utils/locale_builder.lua
+++ b/utils/locale_builder.lua
@@ -3,6 +3,31 @@ local tostring = tostring
 local setmetatable = setmetatable
 local getmetatable = getmetatable
 
+--- Helper class for concatenating LocalisedStrings / strings.
+-- strings and LocalisedStrings can be combined in any order.
+-- Multiple calls to add will automatically split the LocalisedStrings into a linked list
+-- when needed to prevent exceeding 20 parameter limit imposed by Factorio.
+-- However, if you pass in LocalisedStrings that exceeds 20 parameters then it will fail.
+--
+-- @usage
+--  LocaleBuilder = require 'utils.locale_builder'
+--  local locale_string = LocaleBuilder
+--      .add({'common.fail_no_target', 'player_name'})
+--      :add({'', '- a literal string'})
+--      :add('- short hand for literal string')
+--      :add(3):add(true) -- also works if convertable to string
+--
+-- Notice use of :add rather than .add for chaining calls.
+--
+-- local part1 = {'', 'part', ' ', 'one'}
+-- local part2 = LocaleBuilder.add('part'):add(' '):add('two')
+-- local part3 = LocaleBuilder.add('part'):add(' '):add('three')
+--
+-- local result = LocaleBuilder.add(part1):add(part2):add(part3)
+--
+-- If you store the LocalisedStrings in global, when you fetch from global you need to restore
+-- the metatable to be able to use :add calls. To do that use
+-- LocaleBuilder.add(global_stored_locale_string)
 local Public = {}
 
 local add