`embed-lgpl-docs` needs post-processing to make documentation valid and solve warnings
From !725 (comment 852087), so that we don't forget :)
Documenting for future reference: in the linked MR docs are now build-tested by the regular pipeline, showing quite some warnings lately (mainly related to the addition of autolinks
and intra-doc-links
in rustdoc
). See for example the latest run on master
as of writing: https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/-/jobs/8363310.
-
Links to preprocessor defines that do not exist anywhere in scope: [GstValueArray](GST_TYPE_ARRAY)
- these should probably be#GST_TYPE_ARRAY
or%GST_TYPE_ARRAY
in the source; -
URLs that should have been auto-links wrapped in <>
, otherwise they are not clickable; -
Links to ffi functions: [Rendering settings](ges_pipeline_set_render_settings)
- this is valid if the link wasffi::ges_pipeline_set_render_settings
, but the documentation should obviously link to the safe function:Self::set_render_settings
.
EDIT: This pattern seems more prevalent in the source, we probably just need to map[](<something linkable>)
with C symbols just like we do for[#%]
already; -
[something]
pattern is detected as intra-doc-link, ie.[0,1]
. These should simply be escaped as`[0,1]`
in the documentation IMO.
Future improvements, not necessarily related to these warnings:
-
(gir) Stop emittingWill be fixed by https://github.com/gtk-rs/gir/pull/1086;Feature: `XXX`
when https://github.com/gtk-rs/gir/issues/1079 is solved: feature requirements are already displayed in a nice, uniform, obvious, consistent way. No need to repeat it in text -
C source does not use @
/#
everywhere, leading to missing links.
Part of these issues are probably better moved to the respective (GStreamer-XXX C repos, gir
), but at least we can back-reference here and cross them off.