obs-studio
obs-studio copied to clipboard
obsproject
docs: Add missing sceneitem functions
Description
Adds functions related to selected scene items and show/hide transitions of sceneitems.
I did see that obs.h says that the ...selected and ...locked functions are supposed
to be replaced, but ...locked is documented.
I had not added docs for other related functions yet, since I have yet to
figure out what they do (like obs_sceneitem_transition_load, obs_sceneitem_save,
and obs_sceneitem_force_update_transform).
Motivation and Context
Missing documentation for some functions.
How Has This Been Tested?
Built the docs and viewed the html file in the browser (with a webserver).
Types of changes
- Documentation (a change to documentation pages)
Checklist:
- [x] My code has been run through clang-format.
- [x] I have read the contributing document.
- [x] My code is not on the master branch.
- [x] The code has been tested.
- [x] All commit messages are properly formatted and commits squashed where appropriate.
- [x] I have included updates to all appropriate documentation.
Do i need to run clang-format with this kind of PR?
No. If nothing covered by clang-format has changed (e.g., C/C++ files), then clang-format does not need to be run.
In the header, it seems like obs_sceneitem_set_show_transition and obs_sceneitem_set_show_transition_duration are not marked deprecated, but the others are, which seems like an oversight. Do I still consider them all the transition functions deprecated?
As for showing they are deprecated, all the existing deprecation in the docs are done only with one function, unlike this where I combined the new function with the old functions (since I didn't know beforehand). What do you suggest I do? Separate the new functions from the old functions, then put a deprecation warning on the old ones?
Also, the existing deprecation notes only said "27.2.0", but these functions were deprecated in 27.2.4. Which version should I write for this one?
Also, what about the other undocumented sceneitem functions? Should i put them in even without descriptions for now?
Made it so the deprecated functions are separate from the new ones. It is a bit long though due to their number, so is it a good idea to just combine them such that their descriptions would just say "sets/gets..."?
Currently looks like:
Suggested change looks like:
My opinion is that the ; ... otherwise is fine, especially considering that it's just a bool, it's either show or hide. I feel like the additional words do not contribute much, other than for readability reasons (which is arguable, since there are more words for saying the same thing that can't be misunderstood imo). That said, I have no strong feelings on the matter, and I'm fine either way, so just say the word if the suggested changes should be applied.
For some of them, like
I actually like the slight change.
I also noticed an oversight of mine that you pointed out
where returns is wrong, and that will definitely be added.
Again, just say the word if the suggested changes on the ; ... otherwise parts are better, I'm fine with it.
since there are more words for saying the same thing that can't be misunderstood imo)
I do not think that semi-colons are universally understood, and I do not think the implied words hidden by the use of "otherwise" are universally understood. In technical documentation, I prefer explicit text over implicit text. Would welcome a second opinion from @gxalpha or @WizardCM since they are usually involved on documentation PRs.
Applied all suggested changes, but changed one to this:
the suggested was "will set", i changed it to "will return"
