Difference between revisions of "User talk:BryanDerksen"

Revision as of 22:17, 21 July 2009

Function article conventions

At some point I'll certainly dive in to the whole wiki but my primary concern right now is generating the pages for the scripting section. I have an application (the same one I used to produce the dascript.php GeSHi configuration file) which would be capable of mass producing the pages for each native function and helping to produce the pages for the constant groups which can then all be loaded into the wiki en masse. In order to do this though we (as a group) need to decide on the naming conventions (i.e. do we add a prefix, suffix, nothing) and the basic layout of the page. I would also like to avoid putting example scripts directly on the page and instead transclude them from a "script library" section. That way if we need to/want to correct an example we only need to do it once. --Sunjammer 00:31, 21 July 2009 (UTC)

If we put the consistent stuff (name, parameters, return value, etc.) into a template or a set of templates when we auto-generate the script pages, we'll be able to update the layout of the page later on without having to re-edit everything. I was planning on doing that with the event types that I just spent a bit of time splitting out into individual articles but since we don't currently have the parserfunctions extension installed I couldn't come up with something robust enough for my tastes - I'll go back and re-edit those pages later on when we do (parserfunctions are definitely at the top of my "we need this" list right now).

What I'm thinking is a template that takes something like the doxygen headers already in place on some of the existing functions. So this:

/** @brief Returns a creature with a specifc AI Status
*
* When looking for a target of type SELF: the function will return OBJECT_SELF if the status is valid
* When looking for a target of type ALLY: the function will return the nearest ally with the status
* When looking for a target of type ENEMY: the function will return the nearest enemy with the status
*
* @param nAIStatus the status being checked for if active on a creature
* @param nTargetType the target type of creature we are looking for that might have the specified status
* @param nCommandType type of command - if ability the condition will avoid returning an enemy that has an ability applied
* @param nCommandSubType subtype of command - if ability the condition will avoid returning an enemy that has an ability applied
* @returns A creature of a specific type (self, ally, hostile) that has the status applied, OBJECT_INVALID otherwise
* @author Yaronv
*/
object _AI_Condition_GetCreatureWithAIStatus(int nAIStatus, int nTargetType, int nCommandType, int nCommandSubType, int nTacticID);

Would get turned into this:

{{dafunction header
|name = _AI_Condition_GetCreatureWithAIStatus
|brief = Returns a creature with a specifc AI Status
|param1type = int
|param1name = nAIStatus
|param1desc = the status being checked for if active on a creature
|param2type = int
|param2name = nTargetType
|param2desc = the target type of creature we are looking for that might have the specified status
.
.
.
|returnstype= object
|returnsdesc= A creature of a specific type (self, ally, hostile) that has the status applied, OBJECT_INVALID otherwise
|sourcefile= ai_conditions_h
|sourcemodule= Core Resources
}}

Which, via the magic of templating and fancy parserfunctions and whatnot, gets turned into a beautifully-formatted informational header at the top of the article. If the function doesn't have good doxygen comments the template would have empty desc fields left for editors to fill in later on.

My inclination for article naming conventions is to not have any prefixes or whatnot, to make linking easier - just throw [[]] around the function's name and you're there. BryanDerksen 00:55, 21 July 2009 (UTC)

Oh, your transcludable example script library is a good idea, too. I didn't address it above because it won't need to have as much standardization set in stone from the outset. :) BryanDerksen 01:01, 21 July 2009 (UTC)

I assume the goal is to create user-friendly pages that look something like the NWN Lexicon's pages or MSDN? If that is the case can you can mock up a single (for example CreatePool since it already exists), export it and upload the XML to the Social Site (or email it to me directly)? I can then tweak my application and produce a test page, send you the XML which you can import into the Wiki. If all goes well and we are happy with the results I can the produce a page for all 600+ core function in script.ldf at the touch of a button! I can also produce an updated version of the GeSHi config file. After that we can repeat the process for the various core libraries as required.

I would also suggest that rather than putting everything under a single Script category we use different categories to distinguish between the DAScript language (i.e. the reference material) and articles on scripting in DA (i.e. the instructional material). I think DAScript for the reference material and either DAScripting or Scripting for the instructional material.

--Sunjammer 11:46, 21 July 2009 (UTC)

Yeah, I wouldn't want to put 600 articles under one category anyway :) (except for purely housekeeping reasons, perhaps). We'll probably want to categorize these things based on what sort of function they perform, so we could have category:character generation functions, category:event functions, and so forth. Seems likely to me that this is how they'll usually be referenced, a builder will have a particular task he wants to do and will want to see what functions are relevant to it. I'll mock up a nonfunctional version of the template today since I've already got a good start on the parameters we'll need up above, and solicit some more input from scripters on the beta forum to make sure I'm not overlooking anything basic. BryanDerksen 15:14, 21 July 2009 (UTC)

I've added an alternative version of the mock up on my Discussion page. Let me know what you think.

--Sunjammer 21:17, 21 July 2009 (UTC)