User:Kebap/documentation-in-wiki

From Mudlet
< User:Kebap
Revision as of 22:30, 7 May 2018 by Kebap (talk | contribs) (Created page with "{{TOC right}} == History == * [https://github.com/Mudlet/Mudlet/issues/1149 Github issue 1149] - gathering missing documentation for public functions * [https://github.com/Mud...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

History

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.

Internal functions

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 this will remain in code, until a new place is settled:

Undocumented / Deprecated functions

Some functions are publicly available but will still not be documented in manual, for example if they are deprecated:

  • Vadi says: closeUserWindow 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.
  • dirToString - more of an internal function as suggested by SlySven
  • dirToNumber - more of an internal function as suggested by SlySven
  • loadRawFile - more of an internal function as suggested by SlySven
  • setMapperView - seems broken as suggested by SlySven

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)

Documentation to be added to wiki

  • auditAreas - description details suggested by SlySven
  • resizeUserWindow
  • removeMapMenu
  • getMapMenus
  • cut
  • setWindowWrapIndent
  • getAllAreaUserData - description details suggested by SlySven
  • getRoomChar - description details suggested by SlySven
  • insertHTML
  • setMergeTables
  • pasteWindow
  • setDefaultAreaVisible - description details suggested by SlySven
  • setDoor - - description details suggested by SlySven
  • hideGauge(gaugeName) - Vadi says, this is publicly available. GUIUtils.lua to be reviewed.
  • getOS

Files reviewed

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

  • /src/TLuaInterpreter.cpp - fixed
  • /src/Mudlet-lua/lua/CoreMudlet.lua - in work
  • /src/Mudlet-lua/lua/DB.lua
  • /src/Mudlet-lua/lua/DebugTools.lua
  • /src/Mudlet-lua/lua/GMCP.lua
  • /src/Mudlet-lua/lua/GUIUtils.lua
  • /src/Mudlet-lua/lua/KeyCodes.lua
  • /src/Mudlet-lua/lua/LuaGlobal.lua
  • /src/Mudlet-lua/lua/Other.lua
  • /src/Mudlet-lua/lua/StringUtils.lua - fixed
  • /src/Mudlet-lua/lua/TableUtils.lua
  • /src/mudlet-lua/lua/geyser/Geyser.lua
  • /src/mudlet-lua/lua/geyser/GeyserColor.lua
  • /src/mudlet-lua/lua/geyser/GeyserContainer.lua
  • /src/mudlet-lua/lua/geyser/GeyserGauge.lua
  • /src/mudlet-lua/lua/geyser/GeyserGeyser.lua
  • /src/mudlet-lua/lua/geyser/GeyserHBox.lua
  • /src/mudlet-lua/lua/geyser/GeyserLabel.lua
  • /src/mudlet-lua/lua/geyser/GeyserMapper.lua
  • /src/mudlet-lua/lua/geyser/GeyserMiniConsole.lua
  • /src/mudlet-lua/lua/geyser/GeyserReposition.lua
  • /src/mudlet-lua/lua/geyser/GeyserSetConstraints.lua
  • /src/mudlet-lua/lua/geyser/GeyserTests.lua
  • /src/mudlet-lua/lua/geyser/GeyserUtil.lua
  • /src/mudlet-lua/lua/geyser/GeyserVBox.lua
  • /src/mudlet-lua/lua/geyser/GeyserWindow.lua
  • maybe others as well

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
Retrieved from "https://wiki.mudlet.org/index.php?title=User:Kebap/documentation-in-wiki&oldid=4469"