I am a AutoCAD programmer and venturing into SolidWorks API. (I hope its OK! )

I am trying to understand the syntax of the SelectByID2 method and finding it very confusing. (Natural for a newbie).

What I an trying here is to write a detailed explanation so that a newcomer would understand it.

I request experienced users to correct / enhance it so that it is as exhaustive as possible. My comments are in blue

ModelDocExtension::SelectByID2

This method selects the specified entity.

Syntax (OLE Automation): retval = ModelDocExtension.SelectByID2 ( Name, Type, X, Y, Z, Append, Mark, Callout, SelectOption )

Inputs:

Name: Name of object to select or an empty string

I believe this is the name in the FeatureManagerTree and is unique in that particular document. It is not clearly mentioned that if you leave this parameter blank, you must provide non-zero signed values in z,y,z parameters.

Type: Type of object (uppercase) as defined in swSelectType_e or an empty stringv

This is clear and needs no explanation. But it is not clear why this parameter is required in the first place. Since the name uniquely defines the object, its type is obviously defined. Why this additional information is required when it can be left blank.

X,Y, Z:

These are obviously the coordinates of a point. But it is not mentioned that the point should be on the object to be selected.

Also it is not clear:

a. what happens if the point 0,0,0 is on an object to be selected, since default value is 0,0,0.

b. what happens if the user specifies both: name and a point (non-zero values).

c. variant of b above is what if the point does not lie on the object to be selected.

Also the name of the method is sort of misleading. Since it selects objects either by name or location, the method should be called SelectByID2OrLocation

Append:

TRUE

Not already selected: The entity is appended to the current selection list

Already selected: The entity is removed from the current selection list

FALSE

Not already selected:  The current selection list is cleared, and then the entity is put on the list

Already selected: The current selection list remains the same

This is very confusing.

When a object selected already exists in the selection list, it should be logically one of the following thing should happen:

a. object should not be appended to the selection list.

b. existing list should be discarded and new list should be created.

When a object selected does not exists in the selection list, it should be logically one of the following thing should happen:

a. object should not be appended to the selection list.

b. existing list should be discarded and new list should be created.

If selection list is empty then obviously the object should be added to the list.

But the option 'The entity is removed from the current selection list' is little difficult to understand. It is not clear in which situation this shouls happen.

Mark: Value that you want to use as a mark; this value is used by other functions that require ordered selection

Is this value decided by the user or is automatically generated and transparent to the User? What should be the type (long, double, string, alphanumeric) of this value? What are the 'other functions'? What is an 'ordered selection'?

Callout: Pointer to the associated callout.

What is an 'associated callout'?

SelectOption: Selection option as defined in swSelectOption_e (swSelectOptionDefault / swSelectOptionExtensive)

The difference between the two is not obvious.

-------------------

Can you please add explanation so that the syntax is clear to a newcomer.