Template talk:Dafunction

Moved from User talk:BryanDerksen

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)

Moved from User_talk:Sunjammer

• I think we can use the dascript mark up to auto-format the function's prototype: gives for a lighter and more consistent feel
• The parameter/return/source were quite intense with the heavy bolding: used lighter weight and itallics however I had to fudge the indentation

I used definition list markup which is more semantically meaningful than simply italicizing and indenting. I can get the same effect by applying styles to the tags, I'll do that. BryanDerksen 21:31, 21 July 2009 (UTC)

After flipping back and forth a bit I think it loses something without having something to visually distinguish between term and definition, how about leaving the top-level ones bold? I've made a version of CreatePool illustrating this here. BryanDerksen 21:49, 21 July 2009 (UTC)

That looks like a good balance

• Reordered/tweaked subheadings

The "parts" subheading probably should be omitted since the substance inside it will be generated by the header template and won't be independently editable like the other subsequent sections. BryanDerksen 21:31, 21 July 2009 (UTC)

• I think we should use the following subheadings:
  • Description: this should be the official full length description taken from the comments and only updated by people who know what they are talking about

Heh. Most of the functions in the core resources don't really have an "official" description. BryanDerksen 21:31, 21 July 2009 (UTC)

We can make them: the idea was to separate the definition from the observations, etc.

• • Remarks: this is known bugs, issues, workarounds, hints and tips, etc. basically anything that has been established through usage by BioWare or the Community (I stole some of the description to populate the example)
  • Examples: transcluded snippets from the script library
  • See Also: any related functions (not just those in the @sa comments) and any related function groups

NOTE: we can use the dascript config file to automatically link the return/data types. I will add that to the next version of the dascript.php file.

One other small change I'd suggest is the convention of making category names lower-case by default unless there's a specific reason not to, since MediaWiki is case sensitive it's best to go with what's easiest to remember and type. BryanDerksen 21:31, 21 July 2009 (UTC)

Oh, this discussion and the one on my user talk page should probably be moved to Template_talk:Dafunction. I'll do that in a bit if you've no objection?BryanDerksen 21:49, 21 July 2009 (UTC)

I've no objections. Feel free to edit out anything irrelevant.

CreatePool

Reserves a block of memory for a fixed number of a particular type of creature.

int CreatePool(
    resource rTemplate,
    int nPoolSize
);

Parts

Parameters:

rTemplate

The template of the creature to use

nPoolSize

Number of creatures of this template to create

Returns:

TRUE if successful

Source:

script.ldf

Description

Creatures of this type that are spawned with the CreateObject function in this area will use this block of memory, and when creatures of this type die or are set inactive their memory space will automatically be returned to the pool.

The purpose of this function is to allow for endlessly spawning monsters, or similar situations.

Remarks

It should be used under EVENT_TYPE_AREALOAD_PRELOADEXIT. When creatures die or are set inactive they will automatically return to the pool.

Note that pool creatures should have "no permanent death" enabled, otherwise certain effects (such as decapitation) will remain on them when they respawn.

Pool size should be at least twice the number of enemies from that will ever be active simultaneously.

Examples

void main()
{
    // create a pool of 5 skeletons
    CreatePool(R"skeleton.utc", 5);
}

See Also

EVENT_TYPE_AREALOAD_PRELOADEXIT

dascript tags and template parameters

I just did a little experimentation with template:event, and it looks like the <dascript> tag may be problematic in how we're planning to use it here. It prevents template parameters from being substituted inside it, which means we can't build up a function prototype like this inside it. When Jesse's got more spare time than he's got right now I'll see if he can think of a way to change this, but failing that we can fall back on the technique I started fiddling with in the event template - 'faking' the dascript formatting with styles on a div. I'm not going to do much work on it right now though since we can't properly implement it until parserfunctions is installed and the formatting of dascript might change before then anyway. BryanDerksen 19:11, 23 July 2009 (UTC)