vjassdoc

[Barade]

vjassdoc is a simple program written in C++ which generates an HTML API documentation by parsing Jass or vJass code.

License
GPLv2

Requirements

• cmake (minimum 2.6.4)
• g++ or any similar C++ compiler
• gettext
• Boost C++ Libraries
• SQLite3 (database mode, optional)
• Qt 4 (GUI mode, optional)
• KDE 4 (GUI mode, optional)

Current version
0.3

Components:

• vjassdoc
• vjassdocgui
• vjassdoclib

Download
All releases can be found on this website.

Source code
Additionally you're able to get the latest code version by using SVN: svn co https://vjasssdk.svn.sourceforge.net...sssdk/vjassdoc.

Information
Since I wanted to get some more experience with C++ I decided to write a documentation generation program.
It's quite easy to use.
Just type "./vjassdoc --help" (on UNIX systems) to see all available commands.
Note that this is still a beta version and the database creation and addition mode is not really useful yet.
For compilation you'll need make and cmake. Just type "cmake ." or "cmake -G "Make file type" ." to generate all make files.
By typing "make" and "make install" you'll compile and install the program.
Since I am not a Windows user there will probably be some bugs. Just report them to me, please and I will fix everything.
SQLite3 is required for the database creation. The program is able to create SQLite databases with all parsed objects.
It also supports documentation comments (/// Bla or /** Bla */) and some corresponding keywords like @param or @author etc.
The program uses gettext for internationalisation. Supported languages are English, German and Macedonian (unfortunately just some strings :-().
If you want to help to translate the program into other languages please contact me.

Since version 0.3 there's a simple GUI KDE 4 implementation, too for users who do not like using the command line.
Note that this GUI application isn't stable and really useful, yet.

[Vexorian]

I'd suggest you to include an example of code and the generated documentation so people understand what this does.

I'll take a look later, when I have enough time to compile and install the dependencies.

[C2H3NaO2]

I can NOT open the tar archives under windows with 7zip! Other tar archives like Drupal modules are no problem. Later i'll try under my arch linux, but you should fix it.

Btw you should think of a better picture for this. It's not really good to autogenerate a logo that has nothing to do with the tool with ~5 clicks in gimp.

[Vexorian]

1) You are not supposed to open those if you are in windows (unless you want to compile it for some reason?)
2) They are not just tar, they are tar.bz2 , I think you'll first have to extract the bz2 and then the tar part... Linux decompressors generally do that, seems 7zip doesn't.

[Rising_Dusk]

The submission rules require all files be attached to the first post.

[Barade]

Isn't there an exception for tools?
I think I've read that you can link to everything.

@C2H3NaO2:
Don't you like the picture? Of course it is an auto generated one but I really like it and I don't think there will be any problems if I use it further on.
And of course you can try to make a nicer one :-).

At the moment I am working on the database creation optimization. Maybe I will add some options to exclude some kinds of objects from parsing (like comments which aren't really necessary most times).

Some time ago I've start working on an RPM and ebuild file for Linux users but I won't finish it until I'll get some more time.
The package generation implementation of KDevelop 3 isn't that good :-/ and there is still no cmake support (coming with KDevPlatform) which makes it more difficult for me to use it.

[C2H3NaO2]

[quote=Vexorian]1) You are not supposed to open those if you are in windows (unless you want to compile it for some reason?)[quote]
Yes I want to compile it. There is no binary of the last version. And with cygwin it would be pretty easy (i hope).

And I am also interested into the code.

Originally Posted by Vexorian

2) They are not just tar, they are tar.bz2 , I think you'll first have to extract the bz2 and then the tar part... Linux decompressors generally do that, seems 7zip doesn't.

7zip _does_ ít. there is no problem to open the .bz2. The problem is the tarfile.

[Rising_Dusk]

Originally Posted by Barade

Isn't there an exception for tools?

Not in the current iteration of the submission rules. If any exceptions were made in the past, then the staff was not following the resource submission rules at the time. Look at the bottom of the rules here if you'd like to see tool-specific requirements.

[Barade]

Uploaded version 0.2.3 which contains many changes and bug fixes.

Options --private and --textmacros are available now.

[Pyrogasm]

Pardon me, but can you explain what the hell this does–in layman's terms?

[Alevice]

I couldn't be arsed to compile it, but if this is like any documentation generator, what it does is that it generates a document based on a jass file that contatins an object/function reference, much in the vein of the JASS API docs, albeit much simpler in form. Generally JASS systemas aren't that large to require one, but somoen might like it.

[Barade]

Click me. Just an example of a big API documentation.

In the next version you'll be able to use the SQLITE flag for using the database mode because many people do not need it, I think.
Besides I am working on documentation comments like @struct <structname> for all Jass/vJass objects.

If you want to check out the latest version you should be able now to use svn co https://vjasssdk.svn.sourceforge.net...sssdk/vjassdoc.

[Vexorian]

Tried testing but seems to be only extracting comments and library names and the fact the script uses integer and string.

that's the sort of thing extracted from a file like:

libxecollider.j:

library xecollider initializer init requires xefx, xebasic
//****************************************************************
//*
//* xecollider 0.5
//* --------------
//*  A xecollider object is a special effect that has a collision
//* size that can trigger a hit event and also many options to
//* configure its automatic movement.
//*
//*  Please use .terminate() instead of .destroy() this ensures
//* that it will be safe to destroy it (else you would have to
//* worry about destroying it during the animation loop/etc.)
//*
//*  To use this struct is a little different than the other
//* current parts of xe. Instead of just creating the xecollider
//* (which works, but it would only be a xefx that can have speed)
//* you probably need to make it do something special on the
//* unit hit event... For this reason, you need to make a new
//* struct extending xecollider that declares an onUnitHit method
//* you may also declare a loopControl method, very useful, can
//* help you reduce 'attaching'.
//*
//****************************************************************

//================================================================
    globals
        private constant real DEFAULT_COLLISION_SIZE  =   50.0 // These are defaults, on one hand you can change them
        private constant real DEFAULT_MAX_SPEED       = 1500.0 // on the other hand, if a spell relies on the defaults
        private constant real DEFAULT_EXPIRATION_TIME =    5.0 // changing them would make the behavior vary...

        private constant real PI2 = 6.28318 //It might not be wise to change this
    endglobals

    //===========================================================================
    // So, this exists merely so you can declare your own event handler methods
    // if interfaces make your brain blow out, please skip the next four lines.
    //
    private interface eventHandler
        method onUnitHit takes unit hitTarget returns nothing defaults nothing
        method loopControl takes nothing returns nothing defaults nothing
    endinterface

    //===========================================================================
    struct xecollider extends eventHandler
     // use terminate() instead of .destroy() to "kill" the collider.
     // don't worry, terminate will call destroy automatically.

        //============================================================================
        // delegates:
        //   We are delegating a xefx object so that people call all the xefx methods
        //  and member from a xecollider object. This means that from a user
        // perspective a xecollider is also an instance of xefx. 
        //
        //   Notable ones are: .x , .y , .fxpath and .z ,
        // check out xefx's documentation for more info.
        //
        private delegate xefx fx

        //##==========================================================================
        // public variables:
        //
        public real expirationTime = DEFAULT_EXPIRATION_TIME

        // Movement speed for the missile.
        public real speed          = 0.0

        // Speed added per second (notice you can use a negative value here)
        public real acceleration   = 0.0

        // If there is acceleration, it is wise to have a cap...
        public real maxSpeed       = DEFAULT_MAX_SPEED
        public real minSpeed       = 0.0

        public real angleSpeed     = 0.0 //The increment in radians per second to the
                                         // direction angle, allows curved movement.

        private static integer lastSeen = 0
        private group   seen

        //##==========================================================================
        // public methods:
        //

        //----
        // Well, it is a good idea to actually create the missiles.
        // notice that if your custom missile struct needs to declare its own create
        // method, you can call this as allocate(x,y,dir).
        //
        // Sorry, no Loc version.
        //
        public static method create takes real x, real y, real dir returns xecollider
         local xecollider xc= xecollider.allocate()
            set xc.fx = xefx.create(x,y,dir)
            set xc.dir=dir
            set xecollider.V[xecollider.N]=xc
            set xecollider.N=xecollider.N+1
            if(xecollider.N==1) then
                call TimerStart(xecollider.T, XE_ANIMATION_PERIOD, true, xecollider.timerLoopFunction )
            endif
            if(.lastSeen < integer(xc)) then //with this I do group recycling
                set .lastSeen = integer(xc)
                set xc.seen = CreateGroup()
            endif

         return xc
        endmethod

        //----
        // The direction is just the angle in radians to which the missile's model faces
        // and the automatic movement uses.
        //
        method operator direction takes nothing returns real
            return this.dir
        endmethod
        method operator direction= takes real v returns nothing
            set this.dir=v
            set this.fx.xyangle=v
        endmethod

        //----
        // The collisionSize
        //
        method operator collisionSize takes nothing returns real
            return this.csize
        endmethod
        method operator collisionSize= takes real value returns nothing
            set this.csize = value
            //good long attribute name, but we use csize in the loop
            //don't worry this gets inlined, it would also be helpful if
            //I ever decide to add a control for assignment.
        endmethod



        //---
        // targetUnit is a unit to follow (or try to follow), notice that homing
        // options require an angleSpeed different to 0.0
        //
        public method  operator targetUnit takes nothing returns unit
            return this.homingTargetUnit
        endmethod
        public method  operator targetUnit= takes unit u returns nothing
            if(u==null) then
                set this.homingMode=0
            else
                set this.homingMode= .HOMING_UNIT
            endif
            set this.homingTargetUnit=u
        endmethod

        //----
        // targetPoint is a point to reach (or try to reach), notice that homing
        // options require an angleSpeed different to 0.0
        //
        public method setTargetPoint takes real x, real y returns nothing
            set this.homingMode= .HOMING_POINT
            set this.homingTargetX=x
            set this.homingTargetY=y
        endmethod
        public method setTargetPointLoc takes location loc returns nothing
            set this.homingMode= .HOMING_POINT
            set this.homingTargetX=GetLocationX(loc)
            set this.homingTargetY=GetLocationY(loc)
        endmethod

        //----
        // Call this in case you used targetUnit or TargetPoint so the missile
        // forgets the order to home that target.
        //
        public method forgetTarget takes nothing returns nothing
            set this.homingMode = 0
        endmethod
        method terminate takes nothing returns nothing
            if (xecollider.duringExpire ) then
                set this.dead=true
                set this.fxpath=""
            else
                call this.destroy()
            endif
        endmethod

        //--------
        private static timer      T
        private static integer    N=0
        private static xecollider array V
        private static boolean    duringExpire=false
        private static code       timerLoopFunction  //I use a code var so create can be above the timerloop function, more readable
        
        private        boolean dead=false


        private real csize = DEFAULT_COLLISION_SIZE
       


        private          real dir


        private static constant integer HOMING_UNIT =1
        private static constant integer HOMING_POINT=2
        private                 integer homingMode  =0

        private unit homingTargetUnit = null
        private real homingTargetX
        private real homingTargetY





        private method onDestroy takes nothing returns nothing
            call GroupClear(this.seen)
            call this.fx.destroy()
        endmethod


        private static xecollider cinstance
        private static real       newx
        private static real       newy
        private static group      enumGroup
        private static boolexpr   enumBoolexpr

        private static unit array picked
        private static integer    pickedN

        static method timerLoop takes nothing returns nothing
         local integer i=0
         local integer j=0
         local integer c=0
         local xecollider this
         local real d
         local real ns
         local real wa
         local real df1
         local real df2
         local unit u

            set xecollider.duringExpire = true
            loop
               exitwhen (i== xecollider.N )

               set this=.V[i] //adopt-a-instance
               set this.expirationTime = this.expirationTime - XE_ANIMATION_PERIOD
               if(.dead or (this.expirationTime <=0.0) ) then
                   call this.destroy()
               else
                   set ns=this.angleSpeed*XE_ANIMATION_PERIOD
                   if (ns!=0.0) then
                       if(this.homingMode== .HOMING_UNIT ) then
                           set u=this.homingTargetUnit
                           if(GetUnitTypeId(u)==0) then
                               set this.homingMode=.HOMING_POINT
                           else
                               set this.homingTargetX=GetUnitX(u)
                               set this.homingTargetY=GetUnitY(u)
                           endif
                           set u=null
                       endif    
                       if (this.homingMode != 0) then
                           if(ns<=0) then
                               set ns=-ns
                           endif
                           set wa=Atan2(this.homingTargetY - this.y , this.homingTargetX-this.x)

                           //if(wa<0.0) then
                           //    set wa=wa+PI2
                           //endif
                           set df1=wa-this.dir
                           set df2=(PI2+wa)-this.dir

                           if (df1<=0) then
                               if(df2<=0) then
                                   if(df2>=df1) then
                                       set df1=df2
                                   endif
                               else
                                   if(-df1>=df2) then
                                       set df1=df2
                                   endif
                               endif
                           else
                               if(df2<=0) then
                                   if(-df2<=df1) then
                                       set df1=df2
                                   endif
                               else
                                   if(df2<=df1) then
                                       set df1=df2
                                   endif
                               endif
                           endif
                           if(df1<=0) then
                               if(-df1>=ns) then
                                   set ns=-ns
                               else
                                   set ns=df1
                               endif
                           else
                               if(df1<=ns) then
                                   set ns=df1
                               endif
                           endif

                       endif
                       set d=this.dir
                       set d = d + ns
                       if(d>=PI2) then
                           set d=d - PI2
                       elseif(d<0) then
                           set d=d + PI2
                       endif
                       set this.dir = d
                       set this.xyangle = d
                   endif

                   // function calls are expensive, damned we are, long code inside of loop
                   // correct software dev. tells us this should go to another function,
                   // but this is Jass, not real life.
                   set .cinstance = this

                   set ns = this.speed + this.acceleration*XE_ANIMATION_PERIOD
                   if ( ns<this.minSpeed) then
                       set ns=this.minSpeed
                   elseif (ns>this.maxSpeed) then
                       set ns=this.maxSpeed
                   endif
                   set d=((this.speed+ns)/2) * XE_ANIMATION_PERIOD
                   set this.speed=ns
                   set .newx= .x+d*Cos(this.dir)
                   set .newy= .y+d*Sin(this.dir)
                   set .x=.newx
                   set .y=.newy
                   set xecollider.pickedN = 0
                   call GroupEnumUnitsInRange( .enumGroup, .newx, .newy, .csize + XE_MAX_COLLISION_SIZE, .enumBoolexpr)

                   call GroupClear(this.seen)
                   set j=0
                   loop
                       exitwhen (j==xecollider.pickedN)
                       call GroupAddUnit( this.seen, xecollider.picked[j])
                       set j=j+1
                   endloop

                   set .V[c]=this
                   set c=c+1
                   if( this.loopControl.exists and not this.dead ) then
                       call this.loopControl()
                   endif
               endif
               set i=i+1
            endloop
            //call BJDebugMsg("}")
            set xecollider.N=c
            if(c==0) then
                call PauseTimer(xecollider.T)
            endif
            set xecollider.duringExpire = false

        endmethod

        private static method inRangeEnum takes nothing returns boolean
         local xecollider this= .cinstance //adopt-a-instance
         local unit u=GetFilterUnit()
            if not(this.dead) and (GetUnitTypeId(u)!=XE_DUMMY_UNITID) and IsUnitInRangeXY(u, .newx, .newy, .csize) then
                // ah, the advantages of a standardized unit id...

                set xecollider.picked[xecollider.pickedN] = u 
                set xecollider.pickedN=xecollider.pickedN + 1

                if  not IsUnitInGroup (u, this.seen ) then
                    call this.onUnitHit(u)
                endif

            endif
            set u=null
         return false
        endmethod

        //============================================================================
        // you aren't supposed to call doInit yourself, try not to do it.
        //
        static method doInit takes nothing returns nothing
            set xecollider.enumGroup = CreateGroup()
            set xecollider.enumBoolexpr = Condition( function xecollider.inRangeEnum)
            set xecollider.timerLoopFunction = (function xecollider.timerLoop)
            set xecollider.T=CreateTimer()
        endmethod
    endstruct

    private function init takes nothing returns nothing
        call xecollider.doInit()
    endfunction
endlibrary

The source code page could use some highlighting or at least a <pre> tag so it has correct indentation.

[Vexorian]

Barade, did you try that script? I wouldn't like to graveyard this as it is probably a good idea.

[Barade]

Oh sorry, I didn't read this until today. I will test it now and edit my results.
At the moment I am working on modules and implementation support :-/ and of course a better value detection for things like super.method() or thistype.method().

edit: Hmm, I think the program needs a better operator support. It seems like it does not support operators with two tokens like method operator bla. Only method operator[].
I tried it with ./vjassdoc -dhpa --dir output --files test.j and it detected the struct xecollider, the library xecollider, the methods create, doInit, forgetTarget, setTargetPoint, setTargetPointLoc, terminate and timerLoop and some members correctly but it also detected some members which aren't members like this.csize which is at line 127 (the first line of an operator method :-/).

When I added the --private option it still seemed to be correctly (without that member bug).

edit2: Okay, I fixed that operator bug but I still have to test it with your script and to change some things before I'll release version 0.2.4.
Remember that you can use my svn repository to check out the newest version by using svn co https://vjasssdk.svn.sourceforge.net...sssdk/vjassdoc.