Module:Documentation: Difference between revisions

clean up the env table functions and the comments
m>Mr. Stradivarius
(fix revision id code)
m>Mr. Stradivarius
(clean up the env table functions and the comments)
Line 158: Line 158:


function p.getEnvironment(args)
function p.getEnvironment(args)
-- Returns a table with information about the environment, including the title to use, the subject namespace, etc.
--[[
-- This is called from p._main using pcall in case we get any errors from exceeding the expensive function count
-- Returns a table with information about the environment, including title objects and other namespace- or
-- limit, or other perils unknown.
-- path-related data.
--
-- Title objects include:
-- env.title - the page we are making documentation for (usually the current title)
-- env.templateTitle - the template (or module, file, etc.)
-- env.docTitle - the /doc subpage.
-- env.sandboxTitle - the /sandbox subpage.
-- env.testcasesTitle - the /testcases subpage.
-- env.printTitle - the print version of the template, located at the /Print subpage.
--
--
-- Data includes:
-- Data includes:
-- env.title - the title object of the page we are making documentation for (usually the current title)
-- env.subjectSpace - the number of the title's subject namespace.
-- env.subjectSpace - the number of the title's subject namespace.
-- env.docspace - the name of the namespace the title puts its documentation in.
-- env.docSpace - the number of the namespace the title puts its documentation in.
-- env.templatePage - the name of the template page with no namespace or interwiki prefixes.
-- env.docpageRoot - the text of the base page of the /doc, /sandbox and /testcases pages, with namespace.
-- env.compareLink - a URL link of the Special:ComparePages page comparing the sandbox with the template.
--
-- All table lookups are passed through pcall so that errors are caught. If an error occurs, the value
-- returned will be nil.
--]]
local env, envFuncs = {}, {}
local env, envFuncs = {}, {}


-- Set up the metatable. If a nil value is called, we call that function in the envFuncs table and memoize it
-- Set up the metatable. If triggered we call the corresponding function in the envFuncs table. The value
-- in the env table so we don't have to call any of the functions more than once.
-- returned by that function is memoized in the env table so that we don't call any of the functions
-- more than once. (Nils won't be memoized.)
setmetatable(env, {
setmetatable(env, {
__index = function (t, key)
__index = function (t, key)
Line 198: Line 212:
end
end
return title
return title
end
function envFuncs.subjectSpace()
-- The subject namespace number.
return mw.site.namespaces[env.title.namespace].subject.id
end
function envFuncs.docspace()
-- The name of the documentation namespace.
local subjectSpace = env.subjectSpace
if subjectSpace == 0 or subjectSpace == 6 or subjectSpace == 8 or subjectSpace == 14 then
-- Pages in the Article, File, MediaWiki or Category namespaces must have their
-- /doc, /sandbox and /testcases pages in talk space.
return mw.site.namespaces[subjectSpace].talk.name
else
return env.title.subjectNsText
end
end
function envFuncs.templatePage()
-- The template page with no namespace or interwiki prefixes.
local title = env.title
local subpage = title.subpageText
if subpage == message('sandboxSubpage', 'string') or subpage == message('testcasesSubpage', 'string') then
return title.baseText
else
return title.text
end
end
end


Line 250: Line 236:
end
end
return mw.title.new(docpage)
return mw.title.new(docpage)
end
function envFuncs.docpageRoot()
-- The base page of the /doc, /sandbox, and /testcases subpages.
-- For some namespaces this is the talk page, rather than the template page.
local title = env.title
return (env.docspace or title.nsText) .. ':' .. (env.templatePage or title.text)
end
end
Line 271: Line 250:
function envFuncs.printTitle()
function envFuncs.printTitle()
-- Title object for the /Print subpage.
-- Title object for the /Print subpage.
return mw.title.new(env.templatePage .. '/' .. message('printSubpage', 'string'))
return env.templateTitle:subPageTitle(message('printSubpage', 'string'))
end
 
function envFuncs.subjectSpace()
-- The subject namespace number.
return mw.site.namespaces[env.title.namespace].subject.id
end
 
function envFuncs.docSpace()
-- The documentation namespace number. For most namespaces this is the same as the
-- subject namespace. However, pages in the Article, File, MediaWiki or Category
-- namespaces must have their /doc, /sandbox and /testcases pages in talk space.
local subjectSpace = env.subjectSpace
if subjectSpace == 0 or subjectSpace == 6 or subjectSpace == 8 or subjectSpace == 14 then
return subjectSpace + 1
else
return subjectSpace
end
end
 
function envFuncs.docpageRoot()
-- The base page of the /doc, /sandbox, and /testcases subpages.
-- For some namespaces this is the talk page, rather than the template page.
local templateTitle = env.templateTitle
local docSpace = env.docSpace
local docSpaceText = mw.site.namespaces[docSpace].name
-- Assemble the link. docSpace is never the main namespace, so we can hardcode the colon.
return docSpaceText .. ':' .. templateTitle.text
end
end
Line 685: Line 691:
function p.makeEndBoxExperimentBlurb(args, env)
function p.makeEndBoxExperimentBlurb(args, env)
-- Renders the text "Editors can experiment in this template's sandbox (edit | diff) and testcases (edit) pages."
-- Renders the text "Editors can experiment in this template's sandbox (edit | diff) and testcases (edit) pages."
-- Get environment data.
local subjectSpace = env.subjectSpace
local subjectSpace = env.subjectSpace
local templatePage = env.templatePage
-- Get title objects.
local templateTitle = env.templateTitle
local templateTitle = env.templateTitle
local sandboxTitle = env.sandboxTitle
local sandboxTitle = env.sandboxTitle
local testcasesTitle = env.testcasesTitle
local testcasesTitle = env.testcasesTitle
if not templateTitle or not sandboxTitle or not testcasesTitle then
local templatePage = templateTitle.prefixedText
if not subjectSpace or not templateTitle or not sandboxTitle or not testcasesTitle then
return nil
return nil
end
end
Anonymous user