Better Documentation.. maybe?

[Gloryride]

So this has come up more than once while I dev on my 2nd SFS game. That is, the documentation of fancy functions is quite lacking and I waste time and money trying to figure out what actually is happening when I call some of them.

Before I explain a fine example, feel free to tell me the answer is "Buy the source"; I suspect that.. could be the case. If it is, I totally respect that. Maybe you'll receive a large check in the mail.


In my current game (a real-time, persistent strategy game deployed on Facebook), we need to transfer room variable ownership whenever the room owner decides to quit/logoff. It took a coon's age to determine that the server-side execution of..

Code: Select all

SFSApi::leaveRoom(User user,
                      Room room,
                      boolean fireClientEvent,
                      boolean fireServerEvent)

.. deletes all of the leavers room variables before catching the "user left room" event in the room extension. When I explain it like this, I know it probably sounds like its my problem but I look to the documentation of such a function to find out what exactly it does. Unfortunately all that is there is..

Removes a User from a previously joined Room

.. which is pretty self explanatory. Maybe its out of bounds to mention that room vars owned by that user are deleted here as well, or maybe that's documented elsewhere (and I just couldn't find it).

In hindsight, I realize I should have intuitively thought to change variable ownership upon receiving a LeaveRoomRequest rather than a SFSEvent.USER_LEAVE_ROOM, but didn't, thinking to save time not having to write yet another request handler and also knowing I had access to the SFS user in my USER_LEAVE_ROOM callback.


I almost deleted this post after realizing that last bit, its more my fault than anything.. but I'll post it anyways, in case it helps others or sparks some discussion.

[ThomasLund]

I'll definitely point the SFS guys to this post so that they can give some thought to it.

Meanwhile I'll continue on the javadocs - few more days and it should be ready (famous last words)

/Thomas

[Lapo]

Thanks for your comments.

.. which is pretty self explanatory. Maybe its out of bounds to mention that room vars owned by that user are deleted here as well, or maybe that's documented elsewhere (and I just couldn't find it).

There are areas where the docs should be improved, this is certainly one.
However we also accompany the cold and synthetic javadoc with pretty verbose in-depth articles of the main server features, such as RoomVariables.
http://docs2x.smartfoxserver.com/Develo ... chitecture

In there you will find an overview of how they work and their features. In fact the article explains how the "persistent" attribute works, which clarifies what you ask.

Anyways, we'll make sure to provide more details where appropriate or link to documents with more information.

[mente]

Possible typo here:
BuddyMessageRequest(java.lang.String message, Buddy targetBuddy, com.smartfoxserver.v2.entities.data.ISFSObject params)
Creates a new BlockBuddyRequest instance.

[ThomasLund]

Thanks - fixed in SVN