Function list?

Hey all,

Does anyone know of a definitive listing for all the Smaug functions? For instance, a rundown of things like do_look, and such? What would be great is to have a sort of Lexicon, showing the function,what sort of arguments it takes, and an example of how to use it.

Thanks,
Gadush

I've never seen one at all. If you want to at least see a list of arguments, I'm sure you could use grep to do so.

If you ran Doxygen on the code and told it to not hide undocumented functions, I'm sure you'd get exactly what you're looking for. Plus, it would be easy to add documentation in the form of comments to each function.

Sounds pretty cool, maybe it's something someone should produce and then submit to mudbytes for everyone else to share.

Couldn't you just look in mud.h?

No, he is talking about commands. Take for example the "goto" command.

That isn't listed in mud.h for a start. It takes at least 2 forms of arguments:


goto <vnum> e.g. goto 10300
goto <name> e.g. goto Nick



So, a function list might list every available command, and all the ways it could be used. I don't see any easy way of doing it except to look at how each function is implemented and what it makes of the arguments it is given (if any).

Ksilyan seems to believe that Doxygen will do it as an automated process. But either way, I think if someone was willing to take the time/effort to create such a reference guide, it could be pretty useful for plenty of others.

Doxygen can generate lists of function prototypes, not a list of commands in the game. To get those, you can either look at the list of DECLARE_DO_FUN in mud.h, or extract it from the information in table.c with a script of some kind.

If the goal is to document functions then I very strongly recommend that it be done with Doxygen, since that way patches can be submitted to, say, SmaugFUSS, which could include Doxygen-style comments for automatic documentation generation.

If Samson would be willing to accept these patches to the SmaugFUSS source, it would definitely help the community.

I note while I was writing this reply that Ksilyan has already replied. I think his reply was addressing listing what functions exist, not what each possible argument does.

---

I can't offhand see how Doxygen or any other automated process can deduce what the function arguments are automatically. Take for example do_slist.

That does different things (takes branches in the code) depending on if the argument is:

• Absent (echoes "Slookup what?")
  
• "all" - echoes all spells/skills
  
• (number) (number) - spells in that level range
  
• "herbs"
  
• h(number) - a specific herb
  
• ... and so on ...

The only way of documenting all this properly would be to work your way through every function and try to work out what all possible arguments to it do.

Oh, right; I was talking about arguments as in C-code arguments. Nick is of course right: Doxygen clearly can't go through and figure out what the various text string arguments to each in-game command will do. :-)

Still, all that could be added to the function header comments. And having Doxygen comments for all functions, not just in-game commands, would be very useful, if anything just to have the API documentated.

This is something that i would gladly donate some of my time to achieve. If someone would like to co-ordinate this as a part of the FUSS project, i would be more than happy to document a file or 2.

I would have no objection at all to patching in whatever doxygen needs to make the code documentation process easier. I most likely won't have time to do much more than apply various patches but I am willing to incorporate them. Anything that helps make the code easier to understand is a welcome thing.

I have a plan, let me know if there are any serious objections.

I will make a section of this forum available to documenting the SMAUG commands (things that a player or admin might type). This will involve a bit of modification of the forum software so that each command:

• Will be a single post in its own thread (eg. a one page for the "look" command)
  
• Cannot be replied to
  
• Any registered user of this forum can edit the page and amend the contents of it (like a Wiki)
  
• Have some provision to avoid two people modifiying a page at once (like a 30-minute lockout after someone tries to edit a page).

This effectively lets any knowledgeable SMAUG admin contribute by amending the description for any command about which they know something (or more than whoever previously posted).

To kick the project off I have made a Lua script that reads in the commmands.dat file, in order to automatically generate the initial pages (445 commands in my copy).

I am planning to amend this to also read in the help.are file, and merge (as far as it can automatically) the help for each command with the information from the commands.dat file. A typical (generated) page might look like this:

---

---

Now someone might edit that to say exactly what the default equipment is, and now that command is better documented. :)

That's a very good idea, Nick. If we do that in addition to the Doxygen comments, we can have not only better documentation for the in-game commands, but also for the code API. The best of both worlds. :-)

Samson, some time soon I can send you a Doxygen file that, when you run it through Doxygen, can generate the docs. Then, whenever people send you function comment headers, you can run it and out will come the HTML.

All right! Incredible response folks; great to see the level of interest and willingness to provide so much that will benefit all.

Thanks,
Gadush

Sounds like a plan. When its all set up I'll see if I can help out a bit as well.

See: http://www.gammon.com.au/forum/bbshowpost.php?bbsubject_id=7115