Is there a way to get maxscript to return what arguments are needed for a given function? Almost like a getPropNames for functions?
I have a stuct consisting of a bunch of functions I've written to be used without a ui and it is going to continue to grow. Some functions I'll use more often than others, so I'm certain that I won't be able to remember the required arguments or even the specific names for all of these functions (I'm already having a difficult time). Although I keep clean code, I find it is a pain to have to go back and search through the script each time I want to call the function to figure what it needs.
What I'm trying to do is basically create a quick reference that is dynamically generated from the struct. I'm writing a function that will collect all other functions in the struct, sort them in alphabetical order, and format them to the listener with the required arguments beside them to provide a quick refresher on how they work.
My current game plan is to store the struct's ms file path in a parameter inside the struct and then just read through the file, collecting any lines that start with "fn " or "mapped fn " as it goes. I'm sure this will work, but it feels flimsy. Does anybody have any suggestions?
Flimsy method it is if you want something automatic / doxygen-like.
Our structs of functions have a .info() function, which basically prints out the struct itself – which at least lists the function names, etc. (as well as a short description of the struct, version number, etc.); that helps with quickly finding the function name, at least. (organizing your functions helps as well – e.g. prefixing them with their intended purpose; all functions that work with strings start with ‘str’, all functions working with bitmap start with ‘bmp’, etc.).
If you want something a little less automatic, but perhaps equally useful-ish, there’s a number of things you could do. Here’s one I’ve seen in a very, very old mIRC scripting guide, that I rather liked – but never implemented (outside of a scripted plugin, to sanity-check input); add a help: parameter.
fn test a b help: = (
if (help != unsupplied) then ( "Here's how you use test: <int>test <intA> <intB>. Returns the result of A+B." )
else (
a+b
)
)
If you just call test(), it will complain about lacking parameters – and the number thereof.
If you then call e.g. “test uhmmm Idunno help:#yesplease”, it will print out the helpful message on how to use the function.
Another option that doesn’t first require the discovery of the number of arguments would be to have -all- your functions require named parameters. E.g.
fn test a: b: help:false = (
if (help) then ( "Here's how you use test: <int>test <intA> <intB>. Returns the result of A+B." )
else (
a+b
)
)
test help:true
Yet other options would include making e.g. a testHelp() function that simply always returns the help line; would be better if it’s for a lean-and-mean function that has to be superfast and you don’t really want to waste CPU time on that if-test.
Edit: Just to note… if you do go down the route of functions using -only- named parameters, you can then easily check if the parameter is unsupplied, and whether it is valid or not, etc. and write out a help message specifically for that parameter.
Hi Richard,
Thanks for the suggestions. I hadn't thought of creating an optional help argument. I like the idea, but I'm worried it might end up requiring a bit more maintenance than I am prepared for. Might come in handy in the future though.
I ended up creating a .info() function like you've described, but with "showSource" and the struct name formatted before the name of the function. When the line is evaluated it takes me straight to the function's location in the struct's script file.
I actually noticed this showSource function the other day in the reference and for some reason just didn’t realize it could solve my problem. Sometimes the solution is staring you right in the face.
Thanks again for the response, appreciate it!
Hey Mat, good find, I think that I have seen that before and completely forgotten about it. Some thing that I started doing some time ago and did it for a number of tools and just stopped was have a help function in ever struct so that I could check what was in the struct and how it worked. however I always found it more time consuming then useful.