fix(axparameter): clarify parameter name format for axparameter API

[lucky-rydar]

Describe your changes

• Add explanatory comment showing both short and fully qualified parameter names are valid
• Use both fully qualified and short parameter names for clear demonstration

Issue ticket number and link

• Fixes Inconsistent API usage in the "axparameter" example #440

Checklist before requesting a review

• I have performed a self-review of my own code
• I have verified that the code builds perfectly fine on my local system
• I have added tests that prove my fix is effective or that my feature works
• I have commented my code, particularly in hard-to-understand areas
• I have verified that my code follows the style already available in the repository
• I have made corresponding changes to the documentation

[FelixNilsson]

I see how this can look a bit inconsistent, however how the ax_parameter_register_callback() functions work is that it will convert the parameter name to the full path name. I.e it does not matter if the input is "IsCustomized" or "root." APP_NAME ".IsCustomized", the former input will be converted to the latter one.

When the callback parameter_changed is called the input name will always be the full name i.e
"root." APP_NAME ".IsCustomized".

So to keep it consistent I would prefer to also change the call to ax_parameter_register_callback() to use the full name.

[lucky-rydar]

...it will convert the parameter name to the full path name...

so the callback registrator and other API can differ "relative" parameter name like IsCustom and full path names so in the result it converts everything to full path?

I think it is also required to add a comment next to ax_parameter_register_callback that will say that both formats of parameter name can be used.

[FelixNilsson]

Yes I agree we will update the documentation to make it clear that both formats can use but it will always be converted to the full path name, and it is the full path name that you get it the callback function.

[lucky-rydar]

@FelixNilsson consider reviewing the updated PR with all the replaced parameter names to fully qualified. Also I have added a comment describing which alternative formats can be used as well.

[FelixNilsson]

Remove R197-198, it is only possible to register callbacks to the ACAPs own parameters.

[lucky-rydar]

Done

[FelixNilsson]

Sorry I missed this but it is not possible to use the full path in the function ax_parameter_add().

I can update the library so that this will work, but it will take sometime until that change is released.

[lucky-rydar]

I believe that if we have same multi format input we will improve consistency. So I think the library should be updated.

I would offer to add here a note also. Once it will be updated on the implementation side, we will remove it and update usage.

BTW, as I dont have any hardware to run it on. Is that possible to request someone to verify how it works?

[FelixNilsson]

Yes we are veryfing the changes before we take them in that is how we noticed this issue.
I will update the library part so hopefully we can get that in to AXIS OS 12.9.

So if you update this now to use the short form we can bring in these changes and then I can update the documentation when the library changes has been delivered.

[lucky-rydar]

ok, I will soon update it to use short name. I will also leave the explanation comment with additional line that says it works for all the API except of ax_parameter_add function

by the way, we need somehow to track who is adding new parameter so for example app "axparameter" cant create parameter with name "root.custom_app.MyParam" because it does not belong to "axparameter", But' that's on your side anyway

[killenheladagen]

Why is this a desirable change?

I understand that it is reasonable to handle the parameters as fully qualified parameters internally, inside libaxparam, but here?

The ability to use the short names must be preserved, since removing that would be a breaking change and has to be announced in advance.

Given that the short name option exists, why would anyone want to use the fully qualified when only dealing with your own parameters? It just leads to more typing and longer code to read. This reasoning also applies to this example, that should focus on API usage and not string concatenation.

It could be an idea to replace one usage of a parameter here with a fully qualified one, just to show that it's possible, but as long as it is valid to use the short form, I'd argue that it's also the best choice for your own code.

[lucky-rydar]

It could be an idea to replace one usage of a parameter here with a fully qualified one, just to show that it's possible, but as long as it is valid to use the short form, I'd argue that it's also the best choice for your own code.

I agree. The original idea was to show that both formats of parameter names are possible so they always converted to full path if needed.

Just because I have never used this API before, that wasn't clear that callback registered in ax_parameter_register_callback is going to expect full qualified path despite the fact we registered for short formatted parameter name. So, this thing I think is needed to be updated in the docs for ax_parameter_register_callback

[lucky-rydar]

@FelixNilsson @killenheladagen Merry Christmas. consider to review pls

[johan-hultberg-work]

Thank you for your contribution!

Our workflow involves cherry-picking external contributions into an internal staging repository for more extensive testing before syncing back to this public repo. Your changes have passed that process and are now merged as part of the sync in #465.

Closing this PR since the changes are covered by the sync PR above. We welcome any future contributions!