[Home] [Downloads] [Search] [Help/forum]

Gammon Software Solutions forum

See www.mushclient.com/spam for dealing with forum spam. Please read the MUSHclient FAQ!

[Folder]  Entire forum
-> [Folder]  SMAUG
. -> [Folder]  SMAUG coding
. . -> [Subject]  Function list?
Home  |  Users  |  Search  |  FAQ
Username:
Register forum user name
Password:
Forgotten password?
(New message)
Subject: Function list?
Name:
Your forum user name.
Register forum user name
Password:
Your forum password.
Forgotten password?
Message:
Message to be posted (in English, please).
Forum codes:
Check this if your message uses 'forum codes' or templates (auto-detected for new posts).
Forum codes Templates

Save this message ...

Subject review (reverse sequence)

Pages: 1 2  

Posted by Nick Gammon   Australia  (18,770 posts)  [Biography] bio   Forum Administrator
Date Wed 21 Jun 2006 11:05 PM (UTC)  [ quote  ]
Message
See: http://www.gammon.com.au/forum/bbshowpost.php?bbsubject_id=7115
- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top
Posted by Nick Cash   USA  (626 posts)  [Biography] bio
Date Wed 21 Jun 2006 01:41 AM (UTC)  [ quote  ]
Message
Sounds like a plan. When its all set up I'll see if I can help out a bit as well.
~Nick Cash
http://www.nick-cash.com
[Go to top] top
Posted by Gadush   (92 posts)  [Biography] bio
Date Wed 21 Jun 2006 12:46 AM (UTC)  [ quote  ]
Message
All right! Incredible response folks; great to see the level of interest and willingness to provide so much that will benefit all.

Thanks,
Gadush
[Go to top] top
Posted by David Haley   USA  (3,881 posts)  [Biography] bio   Moderator
Date Wed 21 Jun 2006 12:07 AM (UTC)  [ quote  ]
Message
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.
David Haley aka Ksilyan
Head Programmer,
Legends of the Darkstone

http://david.the-haleys.org
[Go to top] top
Posted by Nick Gammon   Australia  (18,770 posts)  [Biography] bio   Forum Administrator
Date Tue 20 Jun 2006 10:04 PM (UTC)  [ quote  ]
Message
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:



Command:   newbieset
Handler:   do_newbieset
Min level: 51
Min posn:  any (dead)
Log:       normal

Syntax: newbieset <character>

NEWBIESET puts the default (i.e. Darkhaven Academy) equipment into the
character's inventory.  Recipient must be level 5 or lower.




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

www.gammon.com.au, www.mushclient.com
[Go to top] top
Posted by Samson   USA  (683 posts)  [Biography] bio
Date Tue 20 Jun 2006 05:42 PM (UTC)  [ quote  ]
Message
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.
SmaugMuds.org: http://www.smaugmuds.org - The Smaug MUDs Community Center

"The past was erased, the erasure was forgotten, the lie became truth." -- George Orwell, 1984
[Go to top] top
Posted by Robert Powell   Australia  (349 posts)  [Biography] bio
Date Tue 20 Jun 2006 04:19 AM (UTC)  [ quote  ]
Message
Quote:

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.
EldhaMUD Game Developments
The_Fury: Lead Developer, Head Coder
http://fury.eldhamud2.org
[Go to top] top
Posted by David Haley   USA  (3,881 posts)  [Biography] bio   Moderator
Date Tue 20 Jun 2006 03:29 AM (UTC)  [ quote  ]
Message
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.
David Haley aka Ksilyan
Head Programmer,
Legends of the Darkstone

http://david.the-haleys.org
[Go to top] top
Posted by Nick Gammon   Australia  (18,770 posts)  [Biography] bio   Forum Administrator
Date Tue 20 Jun 2006 03:17 AM (UTC)  [ quote  ]
Message
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.

- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top
Posted by David Haley   USA  (3,881 posts)  [Biography] bio   Moderator
Date Tue 20 Jun 2006 02:54 AM (UTC)  [ quote  ]
Message
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.
David Haley aka Ksilyan
Head Programmer,
Legends of the Darkstone

http://david.the-haleys.org
[Go to top] top
Posted by Conner   USA  (381 posts)  [Biography] bio
Date Tue 20 Jun 2006 12:13 AM (UTC)  [ quote  ]
Message
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.
-=Conner=-
--
Come test your mettle in the Land of Legends at telnet://tcdbbs.zapto.org:4000
or, for a little family oriented medieval fun, come join us at The Castle's Dungeon BBS at telnet://tcdbbs.zapto.org
or, if you just want information about either, check our web page at http://tcdbbs.zapto.org
[Go to top] top
Posted by Nick Gammon   Australia  (18,770 posts)  [Biography] bio   Forum Administrator
Date Mon 19 Jun 2006 09:39 AM (UTC)  [ quote  ]
Message
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).
- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top
Posted by Dace K   Canada  (169 posts)  [Biography] bio
Date Mon 19 Jun 2006 09:29 AM (UTC)  [ quote  ]
Message
Couldn't you just look in mud.h?
ASJ Games - .Dimension 2, Resident Evil, and snippets - oh my!
http://asj.mudmagic.com

Drop by the area archives and find something for your mud. http://areaarchives.servegame.com
[Go to top] top
Posted by Conner   USA  (381 posts)  [Biography] bio
Date Mon 19 Jun 2006 01:39 AM (UTC)  [ quote  ]
Message
Sounds pretty cool, maybe it's something someone should produce and then submit to mudbytes for everyone else to share.
-=Conner=-
--
Come test your mettle in the Land of Legends at telnet://tcdbbs.zapto.org:4000
or, for a little family oriented medieval fun, come join us at The Castle's Dungeon BBS at telnet://tcdbbs.zapto.org
or, if you just want information about either, check our web page at http://tcdbbs.zapto.org
[Go to top] top
Posted by David Haley   USA  (3,881 posts)  [Biography] bio   Moderator
Date Mon 19 Jun 2006 12:32 AM (UTC)  [ quote  ]
Message
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.
David Haley aka Ksilyan
Head Programmer,
Legends of the Darkstone

http://david.the-haleys.org
[Go to top] top

The dates and times for posts above are shown in Universal Co-ordinated Time (UTC).

To show them in your local time you can join the forum, and then set the 'time correction' field in your profile to the number of hours difference between your location and UTC time.

7,395 views.

This is page 1, subject is 2 pages long: 1 2  [Next page]

[Reply to this subject]  Reply to this subject   [New subject]  Start a new subject   [Refresh] Refresh page

Go to topic:           Search the forum

[Go to top] top

[Home]

Written by Nick Gammon - 5K

Comments to: Gammon Software support
[RH click to get RSS URL] Forum RSS feed ( http://www.gammon.com.au/rss/forum.xml )

[Best viewed with any browser - 2K]    [Internet Contents Rating Association (ICRA) - 2K]    [Web site powered by FutureQuest.Net]