search

TaktiCool / CLib

CLib is a Function/Script Library for ArmA 3
23 stars 9 forks source link

Make sure mapGraphicsPosition returns Position3D #49

Closed Krzmbrzl closed 3 years ago

Krzmbrzl commented 3 years ago

As e.g. drawPolygon does not accept 2D positions, this function must indeed return a 3D position.

Missing coordinates are filled in as zero.

Note: This is untested

Krzmbrzl commented 3 years ago

Position3D is actually a data type that is used throughout the SQF documentation and MapGraphicsPosition is used in headers at other places already as well :shrug: https://github.com/TaktiCool/CLib/blob/51efc8d6789fd3861335c7833d8fd545a4d7f854/addons/CLib/MapGraphics/fn_addMapGraphicsGroup.sqf#L35

netfusion commented 3 years ago

Position3D is not a data type cause its still an array. Have a look at: https://community.bistudio.com/wiki/typeName

And please do not mix the remarks section of file header with the parameters. Remarks a not validated and may contain any text.

Parameters should be valid data types only.

Krzmbrzl commented 3 years ago

Well if the only restriction you document on a type is Array, then the reader of the documentation can/will assume that ["This", "is", "an", "array"] is a valid argument for that parameter, which is not the case. And if you expect folks to actually read the code in order to know what they can put into the function, you shouldn't document the parameter types at all :shrug:

And as I said: The main SQF documentation readily uses the positions as types as well.

netfusion commented 3 years ago

@Krzmbrzl The header (except for the remarks section) documents syntactic not semantic requirements. Thus ["This", "is", "an", "array"] should be a (syntactical) valid argument. The remark section should say what behavior can be expected if the parameter is semantically invalid (e.g. return [0, 0, 0]).

jokoho48 commented 3 years ago

@Krzmbrzl The header (except for the remarks section) documents syntactic not semantic requirements. Thus ["This", "is", "an", "array"] should be a (syntactical) valid argument. The remark section should say what behavior can be expected if the parameter is semantical invalid (e.g. return [0, 0, 0]).

i dont think we need to be that vebose because we are it not everywhere else. this pr fixes a issue and is not about the documentation.

i think using types like Position is a totaly valid Type in arma BI it self uses that in there Document and it is even listed under the types as Subcategory

netfusion commented 3 years ago

If this PR would only fix the issue, fine. But there was no issue in the header, so please revert changing it.