docs: Add precision on editable string lists

[Penwy]

Description

This adds a precision on the way editable string properties lists work.

Motivation and Context

The doc states that obs_data_get_string() returns the val parameter of a string list item, which is not true of editable lists, causing potential confusion.

How Has This Been Tested?

Built the doc.
Looked at the doc.

Types of changes

• Documentation (a change to documentation pages)

Checklist:

• My code has been run through clang-format.
• I have read the contributing document.
• My code is not on the master branch.
• The code has been tested.
• All commit messages are properly formatted and commits squashed where appropriate.
• I have included updates to all appropriate documentation.

[sebastian-s-beckmann]

Could you give an example of what exactly happens here? As in, which calls return what with every other type of list and what happens with editable lists?
I saw this being discussed on Discord and from what I understand on first glance, this seems more like a bug to me.

[Penwy]

So when adding an item to a string list with obs_property_list_add_string, you give it two strings, name which is what will get displayed when the user views the list, and val which is the "actual" value of the item.
When an item is selected through the UI, the corresponding item in the data settings object associated to it then gets set to val, and calling obs_data_get_string on it to get the item selected by the user returns val. That's also the behaviour of float and int lists.

But in the case of editable lists (which can only be string lists), the value set by the UI in the data settings object, and as such, what obs_data_get_string returns, is name, not val.

I do perfectly agree that it can be argued to be a bug, but "fixing" it will presumably break a lot, it has been like that, as far as I can see for as long as editable lists have existed.
If you want I can create an issue, to have a tracked discussion on whether or not it should be fixed.

[sebastian-s-beckmann]

Oh I understand what's going on, I'd call it expected, so this PR is probably correct.
Personally I'd probably put the clarification in the :param val: line though, maybe as a note that the parameter is essentially unused?

[Penwy]

I considered that, but found it a bit too bulky on trying it. Can change back to that if you so wish.

[RytoEX]

Do we use N.B. anywhere else in the docs? Does Sphinx recognize this and use a special highlight/rendering? How does this note look when rendered into HTML docs?

Does obs_property_list_insert_string also need a note? Does obs_data_get_string?

The language is "good enough" as-is, but I personally prefer something like this:

If p is of type OBS_COMBO_TYPE_EDITABLE, :c:func:obs_data_get_string will return name instead of val.

Highlight/Format as needed to make it look good in the rendered docs. Word wrap text as needed.

[Penwy]

This is what the current version looks like when rendered.

N. B. is not used anywhere else and sphinx does not recognise it as something special. I couldn't find any similar equivalent of a "footnote" either in the existing docs or in sphinx itself, hence why I used that.

obs_property_list_insert_string does need a note, you're quite right, imo obs_data_get_string does not.

[PatTheMav]

Shouldn't this notice be placed with obs_data_get_string? Because it is an implementation detail of that function that behaves differently given the property type.

This detail is entirely irrelevant to either obs_property_list_add_string or obs_property_list_insert_string and this quirk also does not impact the user of either function at all.

Given that obs_data_get_string is referenced, an interested user would click on that to look up information about that function and it is there that this notice should appear IMO.

[Penwy]

My reasoning with this is that:

• This information is relevant when setting up the property, since that's when those values are defined. A priori, the point of such a property is to be used, so, knowing what actually gets returned when it's used is very relevant to setting it up.
• obs_data_get_string is indeed referenced, but in a sentence that states that it will return val, so there would be no reason for any user to assume the behaviour is different and click on the reference to check.

If you still think that this information is better in obs_data_get_string, I will change the PR, but I do disagree here.

[PatTheMav]

My reasoning with this is that:

• This information is relevant when setting up the property, since that's when those values are defined. A priori, the point of such a property is to be used, so, knowing what actually gets returned when it's used is very relevant to setting it up.
• obs_data_get_string is indeed referenced, but in a sentence that states that it will return val, so there would be no reason for any user to assume the behaviour is different and click on the reference to check.

If you still think that this information is better in obs_data_get_string, I will change the PR, but I do disagree here.

If I implement obs_data_get_string and look up its documentation, I expect it to tell me what it returns. It does not make sense to hide that information somewhere else.

If I implement obs_property_list_add_string, I don't necessarily also implement obs_data_get_string, so putting the information there just adds non-relevant information that has no value to me.

The fact that obs_data_get_string behaves differently is an implementation detail of that function, not of the functions adding or inserting strings to a list.

[PatTheMav]

@WizardCM Looks good to me, wdyt?