ToqueScript Intellisense or Auto-Complete
by Ryan Christensen · in General Discussion · 01/05/2004 (4:14 pm) · 40 replies
Hey all,
I saw someone mention that there may be a module for eclipse IDE (I use this for Java dev / VS.NET For c++ and .NET) that may provide auto-complete for TorqueScript. Has anyone heard of this or seen any IDE's that are capable of this already.
I can delve into if noone else is but I think that intellisense and auto-complete are very nice tools to learning pieces of the SDK. They can help you by seeing all methods easily and simply to speed up your coding.
If anyone has heard anything or knows of an auto-complete/intellisense IDE editor for TS that would be gigantumungus for all of our future free-time and possibly (if all the time added together, where programmers have to look up syntax or case for a method) save a day or two to bask in your arthritis at old age. Play now!
Thanks
RYAN
MendaciousWorlds coming 2004
I saw someone mention that there may be a module for eclipse IDE (I use this for Java dev / VS.NET For c++ and .NET) that may provide auto-complete for TorqueScript. Has anyone heard of this or seen any IDE's that are capable of this already.
I can delve into if noone else is but I think that intellisense and auto-complete are very nice tools to learning pieces of the SDK. They can help you by seeing all methods easily and simply to speed up your coding.
If anyone has heard anything or knows of an auto-complete/intellisense IDE editor for TS that would be gigantumungus for all of our future free-time and possibly (if all the time added together, where programmers have to look up syntax or case for a method) save a day or two to bask in your arthritis at old age. Play now!
Thanks
RYAN
MendaciousWorlds coming 2004
#22
My thoughts on what needs to be in there:
All functions, reguardless of if they are documented or not. For stuff that's not documented, well, you only get MySpecialFunction(%blah, %blah2) - no documenation (this is what I do now). That way, it's in there for cool stuff like autocomplete, and so that the programmer knows what he needs to document.
Datablock definitions should be in there - however, the entire datablock does not need to be loaded into the XML file, just the definition for it. This would be reguardless of if they documented it or not.
$Global variables that are documented need to be in there for sure. $Global variables that are undocumented should probably be in there - it would help with debuging, and again is useful for things like autocomplete. However, without documentation you won't have any context for 'em.
%Locals can be important, but, I think we need to ignore 'em with the exception of items in the function declaration and documentation. If the programmer feels it's REALLY important, put info on the %local in the function documenation. (Or alternately, we can put in sectioning, which does complicate things a bit. But it does give you a better way of handling %locals - just document 'em on your first use inside a function.)
I personally went a little further, and added support for arbitrary @todo's, @see's, etc. But most of those aren't that important for this particular application. Toss 'em in a second file (if you make use of 'em at all)
When storing information about a funciton, element, etc., I would also propose storing the file and line number - makes life easier when dealing with multiple function declarations for the same function in different files, and makes "Goto Definition" much easier to deal with too.
As for doing it from within Torque - well, I've already got that done if we go that direction. I just need to enhance it to deal with XML - but there's a nice little XML resource for Torque already, so, having it spew out XML instead wouldn't be that hard.
But pulling in stuff from the source files - that's a little harder to do from within Torque. The source files would have to be inside the Torque project path (IE - setting under the /fps directory for instance) before Torque can see it. We COULD modify the Resource Manager, but I've been avoiding doing that since it adds some potential problems once Torque can play outside of it's nice little sandbox. But having a nice C++ function that reads the function usage string (as in, from: void Con::addCommand (const char *nsName, const char *name, StringCallback cb, const char *usage, S32 minArgs, S32 maxArgs) - if ya' filled out the console function properly, at least a description and prototype exists for ya) and can spew it back to a variable, gui object, etc. would do most of the work nessisary, but would never be complete as reading the full /// comments. However this would be a lot faster than developing a new cross-platform tool to do the job, and I'm much happier if it's available from within a running copy of Torque, just cause it works with my IDE better that way :-)
Add a nice little -mod function, and both of these could also be called from Stefan's IDE - just have it execute torqueProject.exe -mod GetDocs, and pull the XML file after it's done.
01/08/2004 (7:51 am)
Stefan: Yeah, I had thought about it for a while last night after tryin' to shut down for the night, and I think you are right - using dOxygen's output isn't that good of an idea when dealing with the documentation being loaded into memory for something like intellisense. A single file that's much more streamlined would probably be a better idea (however, eventually I'd like to be able to run through the entire documenation for a project within my IDE - but that's just me and my freakish single-interface issue ;-)My thoughts on what needs to be in there:
All functions, reguardless of if they are documented or not. For stuff that's not documented, well, you only get MySpecialFunction(%blah, %blah2) - no documenation (this is what I do now). That way, it's in there for cool stuff like autocomplete, and so that the programmer knows what he needs to document.
Datablock definitions should be in there - however, the entire datablock does not need to be loaded into the XML file, just the definition for it. This would be reguardless of if they documented it or not.
$Global variables that are documented need to be in there for sure. $Global variables that are undocumented should probably be in there - it would help with debuging, and again is useful for things like autocomplete. However, without documentation you won't have any context for 'em.
%Locals can be important, but, I think we need to ignore 'em with the exception of items in the function declaration and documentation. If the programmer feels it's REALLY important, put info on the %local in the function documenation. (Or alternately, we can put in sectioning, which does complicate things a bit. But it does give you a better way of handling %locals - just document 'em on your first use inside a function.)
I personally went a little further, and added support for arbitrary @todo's, @see's, etc. But most of those aren't that important for this particular application. Toss 'em in a second file (if you make use of 'em at all)
When storing information about a funciton, element, etc., I would also propose storing the file and line number - makes life easier when dealing with multiple function declarations for the same function in different files, and makes "Goto Definition" much easier to deal with too.
As for doing it from within Torque - well, I've already got that done if we go that direction. I just need to enhance it to deal with XML - but there's a nice little XML resource for Torque already, so, having it spew out XML instead wouldn't be that hard.
But pulling in stuff from the source files - that's a little harder to do from within Torque. The source files would have to be inside the Torque project path (IE - setting under the /fps directory for instance) before Torque can see it. We COULD modify the Resource Manager, but I've been avoiding doing that since it adds some potential problems once Torque can play outside of it's nice little sandbox. But having a nice C++ function that reads the function usage string (as in, from: void Con::addCommand (const char *nsName, const char *name, StringCallback cb, const char *usage, S32 minArgs, S32 maxArgs) - if ya' filled out the console function properly, at least a description and prototype exists for ya) and can spew it back to a variable, gui object, etc. would do most of the work nessisary, but would never be complete as reading the full /// comments. However this would be a lot faster than developing a new cross-platform tool to do the job, and I'm much happier if it's available from within a running copy of Torque, just cause it works with my IDE better that way :-)
Add a nice little -mod function, and both of these could also be called from Stefan's IDE - just have it execute torqueProject.exe -mod GetDocs, and pull the XML file after it's done.
#23
proposed XML tagging:
However, if you want to make this more lean, and ONLY worry about information for intellisense or autocomplete, or other cool funciton of choice, we could put all of this in a separate file, and instead use a simplified version:
That saves us a bit in memory, but, I'm not sure there's that much advantage to it. I'd rather just save all the function data in one big ol' file, and if I want to only load a minimal part of the data, well, I just load what I want.
Datablocks:
$Globals
--> too long, see next post -->
01/08/2004 (8:19 am)
I'm waiting on a meeting, so, I'll go just a little further with this... :-) proposed XML tagging:
<function>Function Name
<shortDesc>One Line Description</shortDesc>
<longDesc>Long Description, possibly multiple paragraphs</longDesc>
<param1>Parameter</param>
<paramDesc1>Parameter Description, possibly multiline</paramDesc>
(note - add as many params as there are parameters.)
<todo>What needs to be done description, possibly multi-line or paragraphs</todo>
<see>Reference to other function or documenation</see>
<note>Special notes, possibly multiple paragaphs</note>
<filename>Filename and path (relative to Torque base) function was pulled from. If it's a console function, it just says CONSOLE.</filename>
<line>Line number of the function, or if it's a console functions, just says CONSOLE</line>
</function>However, if you want to make this more lean, and ONLY worry about information for intellisense or autocomplete, or other cool funciton of choice, we could put all of this in a separate file, and instead use a simplified version:
<function>Function Name
<shortDesc>One Line Description</shortDesc>
<param1>Parameter</param1>
<paramDesc1>Parameter Description, possibly multiline</paramDesc1>
(note - add as many params as there are parameters.)
<filename>Filename and path (relative to Torque base) function was pulled from. If it's a console function, it just says CONSOLE.</filename>
<line>Line number of the function, or if it's a console functions, just says CONSOLE</line>
</function>That saves us a bit in memory, but, I'm not sure there's that much advantage to it. I'd rather just save all the function data in one big ol' file, and if I want to only load a minimal part of the data, well, I just load what I want.
Datablocks:
<Datablock>Datablock Name
<shortDesc>One Line Description</shortDesc>
<longDesc>Long Description, possibly multiple paragraphs</longDesc>
<type>Datablock type (IE: ProjectileData)</type>
<todo>What needs to be done description, possibly multi-line or paragraphs</todo>
<see>Reference to other function or documenation</see>
<note>Special notes, possibly multiple paragaphs</note>
<filename>Filename and path (relative to Torque base) function was pulled from. If it's a console function, it just says CONSOLE.</filename>
<line>Line number of the function, or if it's a console functions, just says CONSOLE</line>
</datablock>(Note: 'Type' is something I just added - we need to identify what the datablock is. We could just add that to the short description I suppose, but it seems more appropriate for it to get it's own definition. This isn't JavaDoc / dOxygen data though! If someone skims through the docs for dOxygen and sees something more appropriate, speak up! :-)$Globals
<global>Global variable name (sans "$")
<shortDesc>One Line Description</shortDesc>
<longDesc>Long Description, possibly multiple paragraphs</longDesc>
<todo>What needs to be done description, possibly multi-line or paragraphs</todo>
<see>Reference to other function or documenation</see>
<note>Special notes, possibly multiple paragaphs</note>
<filename>first reference or documented reference of the $global. If it's actually something expected by a console function or the engine, then it should be listed as CONSOLE.</filename>
<line>Line number of the first reference or documented reference of the $global. If it's actually something expected by a console function or the engine, then it should be listed as CONSOLE.</line>
</global>--> too long, see next post -->
#24
Pulling my existing documentation functions out and making them not be part of my IDE and instead just another script in /common would be pretty trivial to do, BTW. Would definitely lessen our development time for getting this to work.
I can also post for the File and arbitrary ToDo's format too - but, I thihk those should go in a second XML file. I toss a lot of stuff in the File documenation already, since I'm trying to build up my IDE to handle spewing out full project documentation for the scripting portion / mods.
So... if ya' like this idea Stefan, let's divide the labor a bit. I'll handle adapting the existing documentation functions I wrote to handle XML output if you'll handle doin' something about pulling in the documentation on console functions from the engine side o' things. Sound acceptable?
01/08/2004 (8:20 am)
Ok, well... that's what I proprose. Feel free to hack that up into little bits and come up with something better ;-) But as a base, I think it's a pretty good starting place, and handles most of the crud needed for the job.Pulling my existing documentation functions out and making them not be part of my IDE and instead just another script in /common would be pretty trivial to do, BTW. Would definitely lessen our development time for getting this to work.
I can also post for the File and arbitrary ToDo's format too - but, I thihk those should go in a second XML file. I toss a lot of stuff in the File documenation already, since I'm trying to build up my IDE to handle spewing out full project documentation for the scripting portion / mods.
So... if ya' like this idea Stefan, let's divide the labor a bit. I'll handle adapting the existing documentation functions I wrote to handle XML output if you'll handle doin' something about pulling in the documentation on console functions from the engine side o' things. Sound acceptable?
#25
I like your initial plans for the documentation standard. I wouldn't mind implementing part of this for the community if needed. It seems that Stephan may be the best choice since he keeps up TIDE so if you want to task Davis Ray or me feel free. It may be like a 3-6 month thing with all of our other initiatives (games!!) but I would be willing to do some work on this.
If the community doesn't want to do it I will implement on my side in windows for C++ and develop an app to create the XML and implement this in a stripped down text editor (one that had markup/color-coding support for TorqueScript)
01/08/2004 (9:09 am)
Hey Davis I agree using a standardized format I only posted the MS way because someone asked on a thread further up. If I were to do this I would only do it as windows platform because that is what I need (and I am sure many others) but I think its excellent that the comunity is willing to do a cross-platform version. I like your initial plans for the documentation standard. I wouldn't mind implementing part of this for the community if needed. It seems that Stephan may be the best choice since he keeps up TIDE so if you want to task Davis Ray or me feel free. It may be like a 3-6 month thing with all of our other initiatives (games!!) but I would be willing to do some work on this.
If the community doesn't want to do it I will implement on my side in windows for C++ and develop an app to create the XML and implement this in a stripped down text editor (one that had markup/color-coding support for TorqueScript)
#26
(Giving you a currious look here) Why write a windows-only tool for a cross platform engine? Then you just made yourself more work later, specially considering the last stats I heard from one of the 21-6 guys put thier Mac sales at 60% - that's a lot to miss out on, and anything that hampers cross-platform development is completely useless to me (even though I do run Windows. But beside my Windows machine is a Linux machine, and a Mac PowerBook beside that.) And you would have make the tool you developed worthless to a good number of Linux and Mac devs on the site. Not discouraging you from building something - just pointing out the obvious.
And Stefan and I both maintain separate IDE's - not sure if you missed that fact or something ;-) Did I mention my IDE in there somewhere? Just in case you don't know, I'm always pimping my TorqueIDE that's built using TorqueScript. (BIG GRIN)
01/08/2004 (9:28 am)
Ryan - it will take about 3 hours to implement XML output for scripting functions. Getting it to import into my IDE will take, oh, about 30 minutes (not sure how long it will take Stefan to get his to pull in XML data, but I'm sure it's not very long). No months of development are nessisary. Most of the stuff is already written. Just need to have an agreement on standard format really, and what is needed in the XML files (as in, how much data).(Giving you a currious look here) Why write a windows-only tool for a cross platform engine? Then you just made yourself more work later, specially considering the last stats I heard from one of the 21-6 guys put thier Mac sales at 60% - that's a lot to miss out on, and anything that hampers cross-platform development is completely useless to me (even though I do run Windows. But beside my Windows machine is a Linux machine, and a Mac PowerBook beside that.) And you would have make the tool you developed worthless to a good number of Linux and Mac devs on the site. Not discouraging you from building something - just pointing out the obvious.
And Stefan and I both maintain separate IDE's - not sure if you missed that fact or something ;-) Did I mention my IDE in there somewhere? Just in case you don't know, I'm always pimping my TorqueIDE that's built using TorqueScript. (BIG GRIN)
#27
I realize the *actual* work will only take a small amount of time however I always have 50 million items on my todo list. I develop professionally and have only weekend and also do contracting so mot alot of time for coding. That is my 3-6 months time. I will not be working on that for 3-6 months straight... If you are a professional developer you know how to pad your timelines with months and not give the "programmers time" to complete. Because you will find something cooler to work on and those timelines go out the window. So today you could have the updates done right?!? lets see em :)
Well I develop in windows.. I am concerned about my game and making *my* development faster... If I can help others that is cool but my main focus is gettimg *my* stuff done. If I were to do this alone I would make it fit my development environment.
I think its necessary to keep the game as a cross platform app (TIDE would have to be cross) but for my purposes my tools can be windows based as that is my background in C++.. much easier for me to crank out.
I perfer an IDE *outside* of the game to edit code in.. Its cool to edit scripts in there but when I am crunching code out I like to have my tools be very responsive etc.
I would be interested in seeing the TribalIDE code since that is an app and you can do much more powerful things with it.
And really in the end the engine is a starting point for us all. You develop the tools you need to fit your environment, the game modules you need, etc. Not all have the time to make it cross-platform but I am sure plenty of peeps could use windows toosl as well. I develop for me and my timelines.. if I can hlep others that's cool but if that's your focus for your development you will never meet *your* game timelines.
I started the thread to ask what the status of this was or if anyone was thinking of doing this. I am sure others have said they could do it in a few hours then they found the AI code and never went back to work on this.
I want to help the community as much as anyone and get help from it but you can't make that your main focus unless you work for GG. make sure to spend enough time on your work as well.
It would be cool for the torque development community to have 1 major script editor with all the bells and whistles that all can contribute to whether in script or not.
01/08/2004 (10:06 am)
Hey Davis,I realize the *actual* work will only take a small amount of time however I always have 50 million items on my todo list. I develop professionally and have only weekend and also do contracting so mot alot of time for coding. That is my 3-6 months time. I will not be working on that for 3-6 months straight... If you are a professional developer you know how to pad your timelines with months and not give the "programmers time" to complete. Because you will find something cooler to work on and those timelines go out the window. So today you could have the updates done right?!? lets see em :)
Well I develop in windows.. I am concerned about my game and making *my* development faster... If I can help others that is cool but my main focus is gettimg *my* stuff done. If I were to do this alone I would make it fit my development environment.
I think its necessary to keep the game as a cross platform app (TIDE would have to be cross) but for my purposes my tools can be windows based as that is my background in C++.. much easier for me to crank out.
I perfer an IDE *outside* of the game to edit code in.. Its cool to edit scripts in there but when I am crunching code out I like to have my tools be very responsive etc.
I would be interested in seeing the TribalIDE code since that is an app and you can do much more powerful things with it.
And really in the end the engine is a starting point for us all. You develop the tools you need to fit your environment, the game modules you need, etc. Not all have the time to make it cross-platform but I am sure plenty of peeps could use windows toosl as well. I develop for me and my timelines.. if I can hlep others that's cool but if that's your focus for your development you will never meet *your* game timelines.
I started the thread to ask what the status of this was or if anyone was thinking of doing this. I am sure others have said they could do it in a few hours then they found the AI code and never went back to work on this.
I want to help the community as much as anyone and get help from it but you can't make that your main focus unless you work for GG. make sure to spend enough time on your work as well.
It would be cool for the torque development community to have 1 major script editor with all the bells and whistles that all can contribute to whether in script or not.
#28
01/08/2004 (12:08 pm)
You know, Torque already knows what all the functions are and such. Maybe it would be more worthwhile to just extend the parser and doc stuff in Torque, rather than devise a whole external file format?
#29
This may be another option as long as it can be easily read back in by the autocomplete functionality.
Ben could you elaborate on ho wyou would use the existing items into a TORQUEIDE that could use this info to make autocomplete happen?
Whoever pulls it off it will look good on your resume to implement autocomplete for a known game engine scripting. Could be very useful on a resume.
01/08/2004 (12:51 pm)
Ben I think this would be wise to approach. This thread I was trying to get an idea of where autocomplete is with Torque and options to get there. I am a convert from UT and unreal script so delving into TORQUE with in the last 3 months and don't know everything about it yet. This may be another option as long as it can be easily read back in by the autocomplete functionality.
Ben could you elaborate on ho wyou would use the existing items into a TORQUEIDE that could use this info to make autocomplete happen?
Whoever pulls it off it will look good on your resume to implement autocomplete for a known game engine scripting. Could be very useful on a resume.
#30
@Davis: whoot, that sounds pretty good :) I also like your XML structures, not much to add/say there... yeah, that Torque XML resource will really come in handy, hehe...
Ben is right though, we should get as many info out of the engine as possible... if we dont have to parse any source file, that's perfect!
I'll look into how to get the engine side scripting info we'd need without actually parsing source code... there has to be an easy way to query TGE for that info :)
So: agreed to standard, get to work! ;)
01/08/2004 (1:30 pm)
@dRawk - Ryan C:Quote:it is, it's written in Java ;)
TIDE would have to be cross
Quote:the source code is available, but it's in Delphi and win only... and TIDE can do everything and more than Tribal can do (and JEdit is also an app... ;) but if you want to look at Tribal code anyways I can search for the download link again... but that Delphi/win limitation is why we started with TIDE in the first place.
I would be interested in seeing the TribalIDE code since that is an app and you can do much more powerful things with it.
@Davis: whoot, that sounds pretty good :) I also like your XML structures, not much to add/say there... yeah, that Torque XML resource will really come in handy, hehe...
Ben is right though, we should get as many info out of the engine as possible... if we dont have to parse any source file, that's perfect!
I'll look into how to get the engine side scripting info we'd need without actually parsing source code... there has to be an easy way to query TGE for that info :)
So: agreed to standard, get to work! ;)
#31
Unless someone comes up with something better, I'm going to continue on the path of adjusting the already existing functionality I have.
Ryan: So do I - millions of things to get done. Full time indie / contractor here too - I just put a higher priority level on certain tools that increase my development speed and accuracy. I already dedicate an hour a day to TorqueIDE if I get the chance to do any game development. Just had my last meeting for the week (WHOOHOO!) so, I'll probably finish an XML output version tonight.
01/08/2004 (1:40 pm)
Problem: The engine only knows about functions loaded in memory. Anything else outside of that doesn't exist until they exec(). And then there's the issue of mutliple function / datablock definitions, etc. That's a big limitation right there. Unless someone comes up with something better, I'm going to continue on the path of adjusting the already existing functionality I have.
Ryan: So do I - millions of things to get done. Full time indie / contractor here too - I just put a higher priority level on certain tools that increase my development speed and accuracy. I already dedicate an hour a day to TorqueIDE if I get the chance to do any game development. Just had my last meeting for the week (WHOOHOO!) so, I'll probably finish an XML output version tonight.
#32
I actually haven't loaded up TIDE but have seen it alot on the posts. I have been using TribalIDE from my Tribes days. I recently finished some UT work and am no full into TORQUE. I think its great though with this community and full source access. If anyone is coming frm UT all you have really is the wiki and no source access is annoying when you hit those native script methods.
01/08/2004 (2:00 pm)
@Davis - sweet i would love to see it something started on this. I probably can't even eek it in until later this month. I do feel that this will be huge for development time decrease and help the learning curve for newer people to torqueScript.I actually haven't loaded up TIDE but have seen it alot on the posts. I have been using TribalIDE from my Tribes days. I recently finished some UT work and am no full into TORQUE. I think its great though with this community and full source access. If anyone is coming frm UT all you have really is the wiki and no source access is annoying when you hit those native script methods.
#33
My wife is working tomarrow night, so, I'll polish the rest off then. It's already spewing XML out, but, it doesn't support all the stuff it needs to yet.
01/08/2004 (11:35 pm)
If anyone wonders if I got the new XML output done - nope. Got it about 50% done. Ended up dealing with a networking job (unscheduled, but they wanted ASAP service), but managed to fit in some dev time after that. I had to make one little format change though to make it valid (I did an XML Duh.) Minor, but just in case someone started writing anything to read the XML file before I got the output functions done:<function>
<Name>function name - it's actually the entire funciton line (IE myCoolFunction(%blah))</name>
.........(rest of it stays the same)
</function>Same goes for Datablocks. Small change, but, an important one :-)My wife is working tomarrow night, so, I'll polish the rest off then. It's already spewing XML out, but, it doesn't support all the stuff it needs to yet.
#34
you are right, Torque only knows about compiled scripts, so I guess we really have to parse them (but you already got that handled, right?), and I guess it wouldnt make too much sense to simply exec all available files cause there may be files you don't really want to execute (test files, broken files etc.) - but it should be possible to get the in-engine part of it directly from a running TGE instance... we'll see :)
01/10/2004 (1:04 am)
Sounding good, Davis :) I will hopefully have some time this weekend, too, to look into exporting engine side script information into XML...you are right, Torque only knows about compiled scripts, so I guess we really have to parse them (but you already got that handled, right?), and I guess it wouldnt make too much sense to simply exec all available files cause there may be files you don't really want to execute (test files, broken files etc.) - but it should be possible to get the in-engine part of it directly from a running TGE instance... we'll see :)
#35
Plus, if you use the exec() all of 'em route, then you still miss out on info like what file it loaded from, and what line it's on. Plus, if you've got multiple versions of a function or datablock, you still wouldn't pick it up. And even if ya picked up the function name and parameters, ya don't pick up any docs for it :-P
I had to make one change to my plan - originally I was gonna use the XML resource. However, two problems with that - 1, I'd have to change it a bit to make it ready to be console usable (not that hard). And 2) only people who've loaded the XML resource into thier project would be able to use this. Not difficult, but, if you aren't interested in persistent objects there's not that much use for it.
So, I'm spewing the XML out directly from my script. Not real hard to do of course, and makes life a little simpler for others - no need for the resource, just exec() the script, and the functionality is available.
01/10/2004 (4:05 pm)
Nod - parsin' 'em isn't much of a problem (as in, already handled :-)Plus, if you use the exec() all of 'em route, then you still miss out on info like what file it loaded from, and what line it's on. Plus, if you've got multiple versions of a function or datablock, you still wouldn't pick it up. And even if ya picked up the function name and parameters, ya don't pick up any docs for it :-P
I had to make one change to my plan - originally I was gonna use the XML resource. However, two problems with that - 1, I'd have to change it a bit to make it ready to be console usable (not that hard). And 2) only people who've loaded the XML resource into thier project would be able to use this. Not difficult, but, if you aren't interested in persistent objects there's not that much use for it.
So, I'm spewing the XML out directly from my script. Not real hard to do of course, and makes life a little simpler for others - no need for the resource, just exec() the script, and the functionality is available.
#36
guess I'll just extend the Resourcemanager then so that you can read the engine source files (and only those, gotta keep that secure somehow... ) and are able parse them from within a script mod...
01/11/2004 (3:54 am)
Hm, thats of course true... you dont get any comments if you just query the engine for available functions... plus all the other drawbacks... doh :Pguess I'll just extend the Resourcemanager then so that you can read the engine source files (and only those, gotta keep that secure somehow... ) and are able parse them from within a script mod...
#37
how about reading a zip file in, containing the engine dir?
you zip it up, throw it in "example" and we can read it in and extract our required info?
thoughts?
01/11/2004 (10:45 am)
Hm, actually I dont think its such a good idea to allow Torque read the engine files (besides that, I didnt have a good idea yet how to do it... I'd need to change the basepath in "platform" and hack the resource manager... hmmm...how about reading a zip file in, containing the engine dir?
you zip it up, throw it in "example" and we can read it in and extract our required info?
thoughts?
#38
Now here's an interesting question - how do we only extract console command documenation. Just look for ConsoleMethod and ConsoleFunction? And do we only look for the documentation string that's embedded in the console function, or do we look for normal JavaDoc style documentation? (Or both)? Either way is workable - the existing functionality I've got will do the job on C++ files just as well as script files. Just wanted an opinion on which approach would be better :-)
01/11/2004 (11:10 am)
That would be workable. I totally agree with you on one thing - letting the ResourceManager play anywhere outside of it's sandbox would lead down a very bad path. I've though more than once about messing with the ResourceManager, and always come to the conclusion that it's a bad idea :-)Now here's an interesting question - how do we only extract console command documenation. Just look for ConsoleMethod and ConsoleFunction? And do we only look for the documentation string that's embedded in the console function, or do we look for normal JavaDoc style documentation? (Or both)? Either way is workable - the existing functionality I've got will do the job on C++ files just as well as script files. Just wanted an opinion on which approach would be better :-)
#39
As for the comments: I'd say both types, the example usage string inside the declaration and the JavaDocs around - if any...
01/11/2004 (12:45 pm)
I'd say see what else besides ConsoleMethod or ConsoleFunction is useful for us (e.g. stuff I posted above - what ConsoleDoc searches for, e.g. addField(), addCommand(), addVariable(), ... - not sure what is up-to-date and deprecated exactly atm)As for the comments: I'd say both types, the example usage string inside the declaration and the JavaDocs around - if any...
#40
No problem - I'll look fro both of 'em. If there's no JavaDoc's asssociated with 'em, then we'll just have to go off of the usage string. I know all the stuff that I've done I didn't use the JavaDoc stuff in it - hm, probably not good thinking on my part :-)
Now, here's a question for 'future problems' - methods, properties, etc. of objects. Any thoughts on the best way to extract 'em? That way in the future, you could do auto-properties / methods listings when you type MySpaceShip. (and get that cool autocomplete thing). Not something I'm going to actually DO right now, but, might be worth discussing real quick so that I don't code myself into a corner on accident ;-) (Probably too late now anyway - still didn't get as much dev time this weekend as planned, but, it's getting pretty close to ready to roll.) The engine knows what all the properties and such for any given object is - how do we either 1) dump it to a file, or 2) (and most prefered to me) dump it into object or array that makes it accessable by script (so that when I'm extracting info from the files, I can just pick this up at the same time and parse it into the file too.)
Of course, with a language that has no need of declares, tracking %local variables to what object they are is gonna be... well, very difficult. I've been thinking about this, and since we're laying out a potential standard documenation format for Torque (if only an unofficial one) we COULD make one slight tweak to the normal JavaDoc + dOxygen doc standard to fix the problem:
(In script documenation)
(XML Output)
The chance, you'll notice, is that the first line of a @param would now contain the type of the parameter. Or the other option would be something like:
And if the person writing the documenation doesn't use the [type] field, no biggie. That wouldn't solve ALL of the problems associated with doing autotype on an object, but might be a helper for both knowing for sure what a parameter was expecting (though, you should already have written that in the docs anyway ;-), and getting at least some of 'em to work.
Since we haven't released anything yet, now's the time to decide if this is important enough to deal with or not - instead of forcing people to go back and change it later ;-)
And, of course, later when more of the normal JavaDoc + dOxygen stuff is supported, { } can be used to hold more information about %locals used within the function - and you could extract from that for use in autocomplete situations. (But it's almost self defeating - since you already have to have declared them in the /// docs before autocomplete would work.)
Man I love TorqueScript - but that lack of a declaration is both good and bad :-)
01/11/2004 (10:42 pm)
Hm - any chance someone who popped up and volunteered to help out could search through current docs, and find out what functionality is current and what has been depreciated? That would be a big help.No problem - I'll look fro both of 'em. If there's no JavaDoc's asssociated with 'em, then we'll just have to go off of the usage string. I know all the stuff that I've done I didn't use the JavaDoc stuff in it - hm, probably not good thinking on my part :-)
Now, here's a question for 'future problems' - methods, properties, etc. of objects. Any thoughts on the best way to extract 'em? That way in the future, you could do auto-properties / methods listings when you type MySpaceShip. (and get that cool autocomplete thing). Not something I'm going to actually DO right now, but, might be worth discussing real quick so that I don't code myself into a corner on accident ;-) (Probably too late now anyway - still didn't get as much dev time this weekend as planned, but, it's getting pretty close to ready to roll.) The engine knows what all the properties and such for any given object is - how do we either 1) dump it to a file, or 2) (and most prefered to me) dump it into object or array that makes it accessable by script (so that when I'm extracting info from the files, I can just pick this up at the same time and parse it into the file too.)
Of course, with a language that has no need of declares, tracking %local variables to what object they are is gonna be... well, very difficult. I've been thinking about this, and since we're laying out a potential standard documenation format for Torque (if only an unofficial one) we COULD make one slight tweak to the normal JavaDoc + dOxygen doc standard to fix the problem:
(In script documenation)
/// Does cool stuff to a string and a FXJellyDonutObject /// /// @param %blah string /// The string you want to have mapped onto the /// MelvFXJellyDonut /// @param %blah2 FXJellyDonut /// The target object
(XML Output)
<function> <name>MyCoolFunction (%blah, %blah2)</name> ......... <param1>blah</param1> <param1Desc>A string that's going to be messed with</param1Desc> <param1Type>string</param1Type> ..........
The chance, you'll notice, is that the first line of a @param would now contain the type of the parameter. Or the other option would be something like:
/// Does cool stuff to a string and a FXJellyDonutObject /// /// @param %blah [string] The string you want to have mapped /// onto the MelvFXJellyDonut /// @param %blah2 [FXJellyDonut] The target object
And if the person writing the documenation doesn't use the [type] field, no biggie. That wouldn't solve ALL of the problems associated with doing autotype on an object, but might be a helper for both knowing for sure what a parameter was expecting (though, you should already have written that in the docs anyway ;-), and getting at least some of 'em to work.
Since we haven't released anything yet, now's the time to decide if this is important enough to deal with or not - instead of forcing people to go back and change it later ;-)
And, of course, later when more of the normal JavaDoc + dOxygen stuff is supported, { } can be used to hold more information about %locals used within the function - and you could extract from that for use in autocomplete situations. (But it's almost self defeating - since you already have to have declared them in the /// docs before autocomplete would work.)
Man I love TorqueScript - but that lack of a declaration is both good and bad :-)
Associate Stefan Beffy Moises
Yeah, I think the documentation style Davis posted is the only way to go since its common standard, cross-platform and used in the engine anyways...
so the first task would be to decide what we want to have in our xml files and then to generate it.
You can use doxygen to create XML for you, but it generates too much information for my likings... I just created XML docs for the engine and it gives me 1 xml file per class which adds up to approx. 50MB of XML :P
It can also parse the .cs files and generate xml, which then gives you one xml file per .cs, but they also include the complete code (each line of code is splitted into several xml tags, which really blows up those xml files... (e.g. "weapon.cs" has 4kb, "weapon_8cs.xml" has 23kb :P)
So my suggestion would be to either extend ConsoleDoc (not sure its cross-platform though!) or Torque itself to generate a XML file(s) for specified source paths (be it engine with cc and h or script with cs and gui).
So the "plan" could look like this:
1) decide what info should really go into the xml files
2) decide if "undocumented" functions etc. should be listed, too
3) evaluate ConsoleDoc for cross-platform compatibility and "usefulness"
4) get ConsoleDoc or (preferably) Torque to create XML documentation files for source and/or script files
5) use those xml files in our IDEs
So I could need assistance especially for 1-4, once I have the xml files I can use the DotComplete plugin and a Java XML parser to get intellisense working pretty soon I guess... of course, any help is welcome on the Java side of things, too! :)
And yeah, of course everything will be available for the community, TIDE is Opensource and hosted on Sourceforge as Davis already pointed out :)