Questions about how to use API gimp_layer_new()

[arya]

When I read the API document of gimp_layer_new(), I'm curious about what are explicit procedure calls in the below quote. 

Quote: Other attributes such as layer mask modes, and offsets should be set with explicit procedure calls.

So I looked into gimp source code for this API usage example and find they don't set the mask mode or offset before adding this layer to the image using gimp_image_insert_layer(). 

Code:

    layer = gimp_layer_new (image, _("Background"),
                             img_a->columns, img_a->rows,
                             image_type,
                             100,
                             gimp_image_get_default_new_layer_mode (image));
     gimp_image_insert_layer (image, layer, NULL, 0);

I have the same confusion for gimp_layer_group_new() but I find the code file above calls gimp_layer_set_mode(), gimp_layer_set_opacity() and other APIs as required in the quote below.

Quote:Attributes such as layer mode and opacity should be set with explicit procedure calls. 

So the questions are: what is the explicit meaning of the two quotes? which APIs should we call and how? Must we call these APIs?
Thank you very much!

[Ofnuts]

This just explains why these attributes are not arguments to the call. If you want specific values, after adding the layer, you use additional API calls to achieve what you want such as gimp_layer_set_offsets (). Since the layer is created with sensible defaults you may not need these additional calls.

[arya]

OK. I got it. Do you think the document should be improved? Otherwise, it may confuse developers like me.

For example, the document of gimp_layer_new() should be 

Quote:Other attributes such as layer mask modes, and offsets should be set with explicit procedure calls, if you need to set non-default values for attributes.

with the red clause added.

[Ofnuts]

(10-27-2021, 10:59 AM)arya Wrote: OK. I got it. Do you think the document should be improved? Otherwise, it may confuse developers like me.

For example, the document of gimp_layer_new() should be 

Quote:Other attributes such as layer mask modes, and offsets should be set with explicit procedure calls, if you need to set non-default values for attributes.

with the red clause added.

Personally, I think it is fine as it is.  I have no second thoughts about what that means.

Otherwise since we are now talking about default values, what are these other attributes? What are the default values for each? How to we make sure that the doc changes if the value changes?

OTOH, this is programming. You can try things in a couple of minutes (which is all the better because sometimes the doc can be wrong)