Public functions missing documentation in wiki

[Kebap]

Looking at /src/mudlet-lua/lua/Other.lua there seems to be an optional parameter to permGroup() command which has not been included in manual, yet. Am I right? Should we update the manual? Are there other updates missing?

Manual: permGroup(name, itemtype) Source: permGroup(name, itemtype, parent)

[vadi2]

It was a feature added recently in 3.1.0, I missed the manual in the documentation update. Mind fixing this?

[Kebap]

Done. This issue can be closed.

[Kebap]

Here are a few functions with missing manual entries I found while working on #1150

debugc closeUserWindow setMainWindowSize auditAreas getMudletLuaDefaultPaths sendATCP tempButtonToolbar permBeginOfLineStringTrigger removeSpecialExit

Need to include in wiki manual as well

[vadi2]

Great find! Some of those are just internal to Mudlet, though I suppose it wouldn't hurt to document most of them.

closeUserWindow should stay undocumented, we've agreed that it doesn't really 'close' anyway, 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.

[Kebap]

Sorry, I think that's wrong. I had checked initLuaGlobals() and all of those above are mentioned there, so I assumed they were available for users. That is why including in the manual makes sense.

You still raise a good question. Where do we want to document internal functions? If they should not be announced to users, they can't go to the wiki, right? Or maybe just a different wiki page, named "not recommended usage for users"?

[vadi2]

Thinking about the list again, it's just getMudletLuaDefaultPaths() that is really internal. I was thinking of auditAreas() as well previously but that would be useful for mappers to run.

Not sure creating a special page just to tell people "you can ignore these functions" is worthwhile - maybe just a paragraph with a list of them?

[Kebap]

No not for users especially, but for developers, because we want documentation in wiki not in source, right?

We could also say, internal functions are documented in source, only external are in wiki, but that might get blurry quickly

[Kebap]

Status update.

Added and ok:

• https://wiki.mudlet.org/w/Manual:Lua_Functions#setMainWindowSize
• https://wiki.mudlet.org/w/Manual:Lua_Functions#removeSpecialExit
• https://wiki.mudlet.org/w/Manual:Lua_Functions#permBeginOfLineStringTrigger

Added, but needs more details:

• https://wiki.mudlet.org/w/Manual:Lua_Functions#sendATCP
• https://wiki.mudlet.org/w/Manual:Lua_Functions#tempButtonToolbar

Not sure if/where to add documentation:

• closeUserWindow

Not sure what to add as documentation:

• debug - with source located in TLuaInterpreter::debug
• auditAreas - with source located in TMap::audit
• getMudletLuaDefaultPaths - with source located in TLuaInterpreter::getMudletLuaDefaultPaths - Actually manual already seems to have description for this under https://wiki.mudlet.org/w/Manual:Lua_Functions#getMudletLuaDefaultPath with a missing S at the end - is this the same thing and just a typo there? Source knows no function with missing S like that.

[vadi2]

Thanks for the update!

getMudletLuaDefaultPaths() is the same thing, it got renamed.

debugc() is the function that is available - and that prints to the Debug window when you've got it open.

[Kebap]

Upcoming IRC changes (3.3) need to be checked in wiki manual, see #1087 for a complete list

[Kebap]

Added and ok:

• https://wiki.mudlet.org/w/Manual:Networking_Functions#getIrcChannels
• https://wiki.mudlet.org/w/Manual:Networking_Functions#getIrcNick
• https://wiki.mudlet.org/w/Manual:Networking_Functions#restartIrc
• https://wiki.mudlet.org/w/Manual:Networking_Functions#setIrcChannels
• https://wiki.mudlet.org/w/Manual:Networking_Functions#setIrcNick
• https://wiki.mudlet.org/w/Manual:Networking_Functions#setIrcServer
• https://wiki.mudlet.org/w/Manual:Basic_Essentials#debugc

Added, but needs an example:

• https://wiki.mudlet.org/w/Manual:Networking_Functions#getIrcConnectedHost
• https://wiki.mudlet.org/w/Manual:Networking_Functions#getIrcServer

Renamed and ok:

• https://wiki.mudlet.org/w/Manual:Miscellaneous_Functions#getMudletLuaDefaultPaths

[Kebap]

@SlySven Could you provide a description for auditAreas() maybe?

[Kebap]

Here is another public function missing documentation:

• TLuaInterpreter::resizeUserWindow

Two internal functions missing documentation - where to put internal documentation?

• calcFontWidth
• calcFontHeight

Are the details of documentation in source still valid? Because source shows more information than wiki. I could just add that there, but not sure if outdated or no:

• playSoundFile - Compare CoreMudlet.lua and wiki manual

[vadi2]

For calcFontWidth() and calcFontHeight(), right above the function definition. For playSoundFile() - I think that information is outdated in the .lua file, by a long shot.

[Kebap]

A few more public functions missing documentation:

• loadRawFile
• removeMapMenu
• getMapMenus
• cut
• setWindowWrapIndent
• setMapperView

To be added to wiki

[vadi2]

Ah man, good find.

[Kebap]

Review TLuaInterpreter.cpp is almost done. Found some additional functions without documentation.

Total list (combined with open issues from above):

• dirToString
• dirToNumber
• loadRawFile
• removeMapMenu
• getMapMenus
• cut
• setWindowWrapIndent
• setMapperView
• auditAreas
• getAllAreaUserData
• getRoomChar
• insertHTML
• setMergeTables
• pasteWindow
• setDefaultAreaVisible

To be added to wiki

Question:

• getAllAreaUserData is already mentioned (and linked to) several times in manual, but has no entry of its own for some reason, links are dead. Was this once in there and got deliberately removed or really just an oversight?

Questionable documentation, can be deleted in source? Or added to wiki, too?

• setDoor -- in wiki less directions are mentioned and special exits than in source comment before function definition, please review and compare

[SlySven]

The ones I can offer input on:

• dirToString internal function and not really part of the User API
• dirToNumber internal function and not really part of the User API
• loadRawFile looks as though it would initiate a replay from a lua script, but as the replay system is not multi-profile safe and we do not have a locking system in place for it to prevent more than one replay being loaded at a time at the moment I wouldn't want to draw undue attention to it right now...!
• setMapperView calls TMap::setView but that is a dummy (dead) function so do not say anything about that call (mayhaps it was a leftover or perhaps a placeholder that never got filled out...)
• auditAreas initiates an audit (consistency check) on the whole map manually - to be added to Wiki I guess.
• getAllAreaUserData needs documenting, but functionally similar to corresponding "Room" function - works best on a 17 or later Map Format that supports area (and map) user data saving.
• getRoomChar needs documenting - returns the single (7-bit) ASCII character assigned as a letter to the room symbol on the 2D map {eventually will get extended to a single UTF-8 grapheme (symbol) if I get my way which could contain several bytes}...!
• setDefaultAreaVisible ought to be documented - added on request of a MUD server coder who wanted to keep unexplored rooms for his MUD hidden until explored and wanted to not make it obvious that there were rooms tucked away in an area by hiding the "default area" with id -1 (i.e. where rooms are first added and where they go to if resetArea is called on them) - should be called with a false argument on profile startup to prevent the "Default area" from being listed in the Area Selection widget on the mapper - but it can be used at any-time a map is present in the profile and behaves correctly {handles hiding the "Default area" if that is actually the currently selected one}.

The setDoor() command functions as documented in the source code (and is matched in functionality by the room exits dialog in the 2D mapper) but produces no visible effect on non XY-plane exits (or XY-plane ones with custom exit lines or that are stubs) in the 2D mapper currently i.e. doors on up, down, in, out and special exits do not currently show up although eventually I will get new code into the mapper to show them (around the same time as a wider range of room characters or "symbols" probably...) I guess😀

[vadi2]

getAllAreaUserData is now documented thanks to Liam DeFey

[Kebap]

There are still a few left. For each of the following, we can either:

• add documentation to wiki, or
• unpublish them from public API, or
• decide they should stay public and undocumented for a specific reason

Do you see any other way to get them out of the published-but-undocumented-somehow limbo state?

(The following list contains edits to reflect the updates happening and discussion posted below here)

• [ ] loadRawFile / loadReplay SlySven said: looks as though it would initiate a replay from a lua script, but as the replay system is not multi-profile safe and we do not have a locking system in place for it to prevent more than one replay being loaded at a time at the moment I wouldn't want to draw undue attention to it right now...! Vadi said: is OK to document. Not all functions are perfect, some have known issues - doesn't mean they shouldn't be documented. Leris said: Code said, this should rather be named loadReplay - so I agree and publish it as such. The original published API stays public for backward compatibility, but is not documented under that name. code said: file name, {may include a relative to profile's \"logs\" sub-directory, or an absolute path}

• [ ] getMapMenus Vadi said: good to document. Leris said: Actually found a bug here & reported it as issue #4138 Vadi said: Lets fix it first :)

• [ ] cut Vadi said: good to document. Leris said: got to test, what does this do, edit text buffer!?

• [ ] setDefaultAreaVisible SlySven said: ought to be documented - added on request of a MUD server coder who wanted to keep unexplored rooms for his MUD hidden until explored and wanted to not make it obvious that there were rooms tucked away in an area by hiding the "default area" with id -1 (i.e. where rooms are first added and where they go to if resetArea is called on them) - should be called with a false argument on profile startup to prevent the "Default area" from being listed in the Area Selection widget on the mapper - but it can be used at any-time a map is present in the profile and behaves correctly {handles hiding the "Default area" if that is actually the currently selected one}. Vadi said: to be honest pretty exotic usecase, I would be surprised if anyone else actually uses this, and maybe surprised if the original requester ended up using it. Too late to be doing anything about it now, good to document. Code said: Once a mapper has been created it will, by default, include the "Default Area" associated with the reserved area Id -1 in the list of Areas shown in the area selection widget. This function will immediately hide that entry if given a true argument and restore it if set to false. The setting is NOT saved and this function was created to address a specific need for that area to not be immediately shown to users for one package writer who needed to hide rooms until they have been "explored". This setting is ALSO present on the last "Special Options" tab of the "Profile Preferences" - although it is hidden until there IS a mapper to apply the setting to. Returns true on successfully setting the desired value or false if there is (not yet) a map display to apply it to. Also throws an Error or returned a nil value - both with an accompied error string - if there are problems.

• [x] removeMapMenu Vadi said: good to document.

• [x] setWindowWrapIndent Leris said: This was actually documented meanwhile, but not linked to in code. --> PR #4127

• [x] auditAreas SlySven said: initiates an audit (consistency check) on the whole map manually - to be added to Wiki I guess. Vadi said: good to document. Code says: Now audits the whole map

• [x] insertHTML Vadi said: other functions already do their job, don't need to document. Leris said: Updated comment to say so --> PR #4140

• [x] pasteWindow Vadi said: other functions already do their job, don't need to document. Leris said: Updated comment to say so --> PR #4140

[vadi2]

loadRawFile is OK to document. Not all functions are perfect, some have known issues - doesn't mean they shouldn't be documented. removeMapMenu, getMapMenus, cut, auditAreas good to document. insertHTML, pasteWindow - other functions already do their job, don't need to document. setDefaultAreaVisible - to be honest pretty exotic usecase, I would be surprised if anyone else actually uses this, and maybe surprised if the original requester ended up using it. Too late to be doing anything about it now, good to document.

[Kebap]

getMapMenus

• Vadi said: good to document.

Actually found a bug here & reported it as issue #4138 Continue to publish documentation before fix arrives? 🤔

loadRawFile

• SlySven said: looks as though it would initiate a replay from a lua script, but as the replay system is not multi-profile safe and we do not have a locking system in place for it to prevent more than one replay being loaded at a time at the moment I wouldn't want to draw undue attention to it right now...!
• Vadi said: is OK to document. Not all functions are perfect, some have known issues - doesn't mean they shouldn't be documented.

Code said, this should rather be named loadReplay - so I agree and publish it as such. The original published API stays public for backward compatibility, but is not documented under that name.

[vadi2]

Lets fix it first :)

[Kebap]

Also TLuaInterpreter::Wait() is published to Lua as wait() but in code is commented as internal function.

Should it be published at all? If so, do we add documentation? Otherwise need to change the comment.

[vadi2]

Not safe and should not be used in general, but only in the context of coroutines like this where it's amazing: https://forums.mudlet.org/viewtopic.php?f=6&t=22875

It was left undocumented for this reason but then the coroutine usecase came up. We can:

• document it and only show examples of use in coroutines
• in the future, integrate coroutines package into mudlet, offer people a different way of scripting?

[vadi2]

@Kebap what's your take?

[SlySven]

IIRC The loadRawFile(...)/loadReplay(...) function is now multi-playing safe - it will reject any usage whilst a replay is in progress in any profile - as part of #1519 .

However I notice that in #4157 @smurfix crippled the original `loadRawFile(...) function so it is not actually functional - which technically broke the backward compatibility promise - though you, @vadi2, approved it.

[vadi2]

Yes, because it did not actually break any scripts - and we haven't had any issues with that in the two years since. So that was a good change :+1:

[ZookaOnGit]

Can we get a relist of missing functions here please? I'll get the staff writers on it.