User:Kebap/documentation-in-wiki

History

• Github issue 1149 - gathering missing documentation for public functions
• Github issue 1150 - establishing the project described below

Project aim

• Put all documentation in wiki for users to read.
• Until now, documentation was also in different lua files in Mudlet code. However, this code documentation is only visible for developers not for normal users.
• On the other hand, sometimes code was documented only there and accidentally not in wiki.
• Sometimes documentation in code was outdated, with or without documentation in wiki at the same time.
• The aim of this project is to put all documentation in wiki, where it can be updated easily, and in code just put a link to wiki.
• Only put user documentation in wiki manual. Do not put documentation there for functions, which are not available for public use in Mudlet. This means, developers would need a different wiki page or place outside wiki for documentation of such internal functions. Until now, internal documentation like calcFontWidth and calcFontHeight will remain in code, until a new place is settled.
  • TODO: Create area in wiki for developers' internal documentation as opposed to user-side docs.

Current status

• Kebap is working on this since 2017, taking much longer than expected, about 70% done.
• Missing documentation will be continuously added / updated in wiki either from code or written anew. Documented functions will not be listed here due to high number. See version history of wiki manual for comparison.
• Below only such functions will be listed, which can't or shouldn't be documented in wiki (yet)
• First batch of changes was published in pull request: https://github.com/Mudlet/Mudlet/pull/1707
• Comments in code follow these templates:
  1. // Documentation: https://wiki.mudlet.org/w/Manual:Lua_Functions#denyCurrentSend
  2. // No documentation available in wiki - internal function
  3. // Documentation: ? - public function missing documentation in wiki
• Case 1 should be common case, 2 will not be avoidable, 3 should be transformed into 1

Functions not documented in wiki

Function	File	Status	Description	Responsible
calcFontWidth	?	done	internal function, keep documentation in source	Vadi
calcFontHeight	?	done	internal function, keep documentation in source	Vadi
closeUserWindow	TLuaInterpreter	done	should stay undocumented, we've agreed that it doesn't really 'close' anyway. Instead, hideUserWindow is there to do the job. It's still left in because it was added eons ago and some scripts could have used it.	Vadi
dirToString	TLuaInterpreter	done	more of an internal function	SlySven
dirToNumber	TLuaInterpreter	done	more of an internal function. Seems like it is not published at all? Comment in source changed accordingly. OK	SlySven
loadRawFile	TLuaInterpreter	to do	to be documented as loadReplay instead	?
setMapperView	TLuaInterpreter	done	seems broken, unpublish it already? Function was published but empty. Removed it with PR #3149	Kebap
insertHTML	TLuaInterpreter	done	just calls insertText, as noted there in wiki	?
auditAreas	TLuaInterpreter	done	OK, documented.	?
resizeUserWindow	TLuaInterpreter	done	was published as resizeWindow and already documented as such. Renamed internal function instead. OK	?
removeMapMenu	TLuaInterpreter	done	OK, documented.	?
getMapMenus	TLuaInterpreter	to do	?	?
cut	TLuaInterpreter	to do	?	?
setWindowWrapIndent	TLuaInterpreter	done	OK, documented.	?
getAllAreaUserData	TLuaInterpreter	done	description details suggested, description added thanks to Liam DeFey	SlySven
getRoomChar	TLuaInterpreter	done	OK, documented. description details suggested	SlySven
setMergeTables	TLuaInterpreter	done	OK, documented.	?
pasteWindow	TLuaInterpreter	done	more of an internal function	Vadi
setDefaultAreaVisible	TLuaInterpreter	to do	description details suggested	SlySven
setDoor	TLuaInterpreter	done	description details suggested	SlySven
hideGauge	GUIUtils.lua	to do	to be reviewed	?
resizeGauge	GUIUtils.lua	to do	to be reviewed	?
showAnsiColors	GUIUtils.lua	to do	to be reviewed	?
getOS	TLuaInterpreter	done	OK, documented	?
solveRoomCollisions	TLuaInterpreter	done	Function was published but empty. Removed it with PR #3150	Kebap
permPromptTrigger	TLuaInterpreter	done	OK, documented	Vadi
setOverline	TLuaInterpreter	done	OK, documented	SlySven
setReverse	TLuaInterpreter	done	OK, documented	SlySven
gmod etc.	?	to do	Briefly mentioned in Manual:Supported_Protocols#Managing_GMCP_modules, but not documented properly, while folded in Mudlet forever, says demonnic	?

Files reviewed

Which files have been checked yet and have their documentation updated in wiki?

Status	File	Size	Description
done	/src/TLuaInterpreter.cpp	559 KB	moved many functional documentation from source to manual
to do	/src/mudlet-lua/lua/CoreMudlet.lua	42 KB	needs work, obsolete file containing only documentation
to do	/src/mudlet-lua/lua/DB.lua	60 KB	needs work, moving functional documentation to manual
done	/src/mudlet-lua/lua/DebugTools.lua	7 KB	moved many functional documentation from source to manual
done	/src/mudlet-lua/lua/GMCP.lua	5 KB	seems fine, only internal functions for handling GMCP
to do	/src/mudlet-lua/lua/GUIUtils.lua	50 KB	needs work, defines color_table and functions
to do	/src/mudlet-lua/lua/KeyCodes.lua	14 KB	needs work, defines mudlet.key table which was not found in manual
to do	/src/mudlet-lua/lua/LuaGlobal.lua	6 KB	not sure
to do	/src/mudlet-lua/lua/Other.lua	27 KB	needs work, moving functional documentation to manual
done	/src/mudlet-lua/lua/StringUtils.lua	3 KB	moved many functional documentation from source to manual
to do	/src/mudlet-lua/lua/TableUtils.lua	10 KB	needs work, moving functional documentation to manual
done	/src/mudlet-lua/lua/TTSValues.lua	1 KB	seems fine, only values for Text to Speech, already in manual
done	/src/mudlet-lua/lua/utf8_filenames.lua	116 KB	seems fine, only overwrites existing lua functions
done	/src/mudlet-lua/lua/geyser/Geyser.lua	1 KB	seems fine, contains only comments
unsure*	/src/mudlet-lua/lua/geyser/GeyserColor.lua	6 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserContainer.lua	11 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserGauge.lua	6 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserGeyser.lua	3 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserHBox.lua	2 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserLabel.lua	24 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserMapper.lua	2 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserMiniConsole.lua	8 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserReposition.lua	1 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserSetConstraints.lua	6 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserTests.lua	6 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserUtil.lua	2 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserVBox.lua	2 KB	first decide on Geyser documentation, see below
unsure	/src/mudlet-lua/lua/geyser/GeyserWindow.lua	6 KB	first decide on Geyser documentation, see below

• * Geyser documentation is still located outside wiki, being created semi-automatically from source.
  • Think about where and how to put Geyser documentation in wiki exactly
  • Manual:Geyser is already reserved for the Geyser introduction tutorial
  • Maybe Manual:Geyser Functions would be an appropiate site name
  • Then in there, how to group the different Geyser modules and their respective functions?
  • Until now, all "Functions" pages have one level, but Geyser may need two: modules and their functions
• Are there more .cpp files defining lua functionality? Maybe create a reverse look-up table to see which gets defined where.

Tools used for project

• my branch has current status
• Useful Lua commands:
  • lua debug.getinfo(replace) - Find out, in which file is function "replace" (or others) defined?

Additional findings

• Some functions internally have a different name than the later published version. Review and maybe rename internal functions?
• Some files only have documentation, but no code in them. The code is in Mudlet core directly for example. We delete these files, put documentation in to core.
  • CoreMudlet.lua --> TLuaInterpreter.cpp