diff --git a/subprojects/gst-docs/markdown/contribute/index.md b/subprojects/gst-docs/markdown/contribute/index.md index 5ae75f1e7e..a682da265d 100644 --- a/subprojects/gst-docs/markdown/contribute/index.md +++ b/subprojects/gst-docs/markdown/contribute/index.md @@ -655,6 +655,73 @@ It's of course fine for another developer to assign a merge request with a `Merge in X` label to Marge immediately if they think it's fine to go in now and don't expect further comments or review being needed by others. +### Fixing Since tags + +Since a few releases, CI runs checks to ensure that all new symbols added +as public API are marked with a Since tag in their docstrings. + +If the documentation job rejects your MR with: + +``` +ERROR: [check-missing-since-markers]: (missing-since-marker): /some/path: Missing since marker for GST_SOME_SYMBOL +``` + +You should be able to get rid of the warning by adding a new gtk-doc comment +in the relevant source or header file with such contents: + +``` +/** + * GST_SOME_SYMBOL: + * + * some description of the symbol purposes + * + * Since: 1.XX + */ +``` + +A common mistake for the docstring is to omit the description paragraph: + +``` +/** + * GST_SOME_SYMBOL: + * + * Since: 1.XX + */ +``` + +This will *not* parse as valid gtk-doc syntax. + + +If your attempt is not enough and you'd rather avoid waiting for CI to try various +docstrings, or you simply want to build your documentation changes *fast* on +your local machine, you can proceed as follows: + +``` +# Make sure you have hotdoc +pipx install hotdoc +# Make sure you have a doc-enabled build +rm -rf build && meson build -Dgpl=enabled -Ddoc=enabled && ninja -C build +# Build the complete documentation once +ninja -C build/ subprojects/gst-docs/GStreamer-doc -v +# Enter the devenv, hotdoc now finds the current devhelp2 files and +# will not emit warnings about incorrect links +ninja -C build devenv +# Go back to the toplevel directory +cd .. +# Build the exact documentation subproject you are interested in, +# this is super fast, adapt command to your case +hotdoc run --conf-file build/subprojects/gst-plugins-bad/docs/mpegts-doc.json --previous-symbol-index subprojects/gst-docs/symbols/symbol_index.json +``` + +Another, less common situation is for the header file the docstring was added in to +be explicitly excluded by the meson build files: some header files are known +to contain gtk-doc like docstrings and to generate a ton of irrelevant warnings, +we ignore those. + +If you have a concern it might be the case you can look at the relevant +hotdoc.json file for your subproject to see exactly what sources are +included / excluded. + ## Backporting to a stable branch Before backporting any changes to a stable branch, they should first be