API doc accuracy

[Guest]

Thought I'd post this here instead of the Bugs section first... just to see if I'm overlooking something...

While messing about with the video::SColor method in the specialFX demo, I noticed it accepted 5 floats, SColorf(f,f,f,f)f)... The Irrlicht 0.12 API docs for SColorf show a constructor using only 4 floats. I've noticed a couple other methods that also accept more parameters than what the API docs describe (tho' I can't remember them at the moment).

If I find discrepancies in the API docs, is the most suitable place to report them in the "bugs" forum? TIA.

[AndyCR]

I can explain the 'some methods taking less parameters' thing, basically, lets take createDevice.

you can do it this way:

createDevice(driverType,
core::dimension2d<s32>(640, 480), 16);

and it will assume the last three booleans were desired to be false. but if you wanted stencil buffer shadows, you would have to:

createDevice(driverType,
core::dimension2d<s32>(640, 480), 16, false, true);

you could, i believe, even simply say:

createDevice();

and it would "guess" what you want depending on default parameters set in the code.

I dont know about the SColor one, im guessing theres something similar, except the fourth value (which im assuming is alpha) can be ommited and will default to opaque. just guessing on that one, im not as used to c++ as i am some languages.

EDIT: you can look up what it will default to if only some or no parameters are passed in the api reference, ie.

IRRLICHT_API IrrlichtDevice* IRRCALLCONV irr::createDevice ( video::E_DRIVER_TYPE deviceType = video::EDT_SOFTWARE,
const core::dimension2d< s32 > & windowSize = core::dimension2d< s32 >(640, 480),
u32 bits = 16,
bool fullscreen = false,
bool stencilbuffer = false,
bool vsync = false,
IEventReceiver * receiver = 0,
const wchar_t * sdk_version_do_not_use = IRRLICHT_SDK_VERSION
)

[hybrid]

Yes, default parameters can be left out in many cases, but the API should show all paramters available, and also the defaults if available. So if the API description does not show these parameters its due to missing doxygen comments and this should be fixed. I think the bug section would be a good place for this discussion, there will be probably lots fo missing elements if you also consider return statements etc.

[Guest]

..but the API should show all paramters available, and also the defaults if available.

That's what I was thinking as well. I've used Doxygen on other code projects and I'm guessing it's a config issue that's causing the omissions. I'll post what I find to the bugs forum when I run across something being left out.

@AndyCR - thx for your time and answer as well.