diff mbox series

[FFmpeg-devel] Makefile: Build complete doc with Doxygen

Message ID 20220924210913.5007-1-epirat07@gmail.com
State New
Headers show
Series [FFmpeg-devel] Makefile: Build complete doc with Doxygen | expand

Checks

Context Check Description
andriy/make_x86 success Make finished
andriy/make_fate_x86 success Make fate finished

Commit Message

Marvin Scholz Sept. 24, 2022, 9:09 p.m. UTC 
Add DISABLEDINSTHEADERS, a variable containing the headers of disabled
libraries. This is needed so that Doxygen does not generate incomplete
documentation when a component is disabled, which is quite unexpected
behaviour and results in warnings due to, among other things, broken
references.
---
 Makefile     | 10 ++++++++++
 doc/Makefile |  2 +-
 2 files changed, 11 insertions(+), 1 deletion(-)

Comments

Marvin Scholz Oct. 11, 2022, 1:27 p.m. UTC | #1 
On 24 Sep 2022, at 23:09, Marvin Scholz wrote:

> Add DISABLEDINSTHEADERS, a variable containing the headers of disabled
> libraries. This is needed so that Doxygen does not generate incomplete
> documentation when a component is disabled, which is quite unexpected
> behaviour and results in warnings due to, among other things, broken
> references.
> ---
>  Makefile     | 10 ++++++++++
>  doc/Makefile |  2 +-
>  2 files changed, 11 insertions(+), 1 deletion(-)
>
> diff --git a/Makefile b/Makefile
> index 61f79e27ae..26714950b7 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -110,7 +110,17 @@ include $(SRC_PATH)/$(1)/Makefile
>  include $(SRC_PATH)/ffbuild/library.mak
>  endef
>
> +define DODISABLEDSUBDIR
> +$(foreach V,$(SUBDIR_VARS),$(eval $(call RESET,$(V))))
> +SUBDIR := $(1)/
> +include $(SRC_PATH)/$(1)/Makefile
> +DISABLEDINSTHEADERS := $$(DISABLEDINSTHEADERS) $$(HEADERS:%=$$(SUBDIR)%)
> +endef
> +
> +DISABLEDFFLIBS := $(filter-out $(FFLIBS),$(ALLFFLIBS))
> +
>  $(foreach D,$(FFLIBS),$(eval $(call DOSUBDIR,lib$(D))))
> +$(foreach D,$(DISABLEDFFLIBS),$(eval $(call DODISABLEDSUBDIR,lib$(D))))
>
>  include $(SRC_PATH)/fftools/Makefile
>  include $(SRC_PATH)/doc/Makefile
> diff --git a/doc/Makefile b/doc/Makefile
> index 25774c7bad..d71a02e408 100644
> --- a/doc/Makefile
> +++ b/doc/Makefile
> @@ -100,7 +100,7 @@ doc/%.3: doc/%.pod $(GENTEXI)
>
>  $(DOCS) doc/doxy/html: | doc/
>
> -DOXY_INPUT      = $(INSTHEADERS)
> +DOXY_INPUT      = $(INSTHEADERS) $(DISABLEDINSTHEADERS)
>  DOXY_INPUT_DEPS = $(addprefix $(SRC_PATH)/, $(DOXY_INPUT)) ffbuild/config.mak
>
>  doc/doxy/html: TAG = DOXY
> -- 
> 2.37.0 (Apple Git-136)

Ping for review, please.
Marvin Scholz Nov. 8, 2022, 1:43 p.m. UTC | #2 
On 24 Sep 2022, at 23:09, Marvin Scholz wrote:

> Add DISABLEDINSTHEADERS, a variable containing the headers of disabled
> libraries. This is needed so that Doxygen does not generate incomplete
> documentation when a component is disabled, which is quite unexpected
> behaviour and results in warnings due to, among other things, broken
> references.
> ---
>  Makefile     | 10 ++++++++++
>  doc/Makefile |  2 +-
>  2 files changed, 11 insertions(+), 1 deletion(-)
>
> diff --git a/Makefile b/Makefile
> index 61f79e27ae..26714950b7 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -110,7 +110,17 @@ include $(SRC_PATH)/$(1)/Makefile
>  include $(SRC_PATH)/ffbuild/library.mak
>  endef
>
> +define DODISABLEDSUBDIR
> +$(foreach V,$(SUBDIR_VARS),$(eval $(call RESET,$(V))))
> +SUBDIR := $(1)/
> +include $(SRC_PATH)/$(1)/Makefile
> +DISABLEDINSTHEADERS := $$(DISABLEDINSTHEADERS) $$(HEADERS:%=$$(SUBDIR)%)
> +endef
> +
> +DISABLEDFFLIBS := $(filter-out $(FFLIBS),$(ALLFFLIBS))
> +
>  $(foreach D,$(FFLIBS),$(eval $(call DOSUBDIR,lib$(D))))
> +$(foreach D,$(DISABLEDFFLIBS),$(eval $(call DODISABLEDSUBDIR,lib$(D))))
>
>  include $(SRC_PATH)/fftools/Makefile
>  include $(SRC_PATH)/doc/Makefile
> diff --git a/doc/Makefile b/doc/Makefile
> index 25774c7bad..d71a02e408 100644
> --- a/doc/Makefile
> +++ b/doc/Makefile
> @@ -100,7 +100,7 @@ doc/%.3: doc/%.pod $(GENTEXI)
>
>  $(DOCS) doc/doxy/html: | doc/
>
> -DOXY_INPUT      = $(INSTHEADERS)
> +DOXY_INPUT      = $(INSTHEADERS) $(DISABLEDINSTHEADERS)
>  DOXY_INPUT_DEPS = $(addprefix $(SRC_PATH)/, $(DOXY_INPUT)) ffbuild/config.mak
>
>  doc/doxy/html: TAG = DOXY
> -- 
> 2.37.0 (Apple Git-136)

Another ping for review, please.
Marvin Scholz Nov. 16, 2022, 5:21 p.m. UTC | #3 
On 24 Sep 2022, at 23:09, Marvin Scholz wrote:

> Add DISABLEDINSTHEADERS, a variable containing the headers of disabled
> libraries. This is needed so that Doxygen does not generate incomplete
> documentation when a component is disabled, which is quite unexpected
> behaviour and results in warnings due to, among other things, broken
> references.
> ---
>  Makefile     | 10 ++++++++++
>  doc/Makefile |  2 +-
>  2 files changed, 11 insertions(+), 1 deletion(-)
>
> diff --git a/Makefile b/Makefile
> index 61f79e27ae..26714950b7 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -110,7 +110,17 @@ include $(SRC_PATH)/$(1)/Makefile
>  include $(SRC_PATH)/ffbuild/library.mak
>  endef
>
> +define DODISABLEDSUBDIR
> +$(foreach V,$(SUBDIR_VARS),$(eval $(call RESET,$(V))))
> +SUBDIR := $(1)/
> +include $(SRC_PATH)/$(1)/Makefile
> +DISABLEDINSTHEADERS := $$(DISABLEDINSTHEADERS) $$(HEADERS:%=$$(SUBDIR)%)
> +endef
> +
> +DISABLEDFFLIBS := $(filter-out $(FFLIBS),$(ALLFFLIBS))
> +
>  $(foreach D,$(FFLIBS),$(eval $(call DOSUBDIR,lib$(D))))
> +$(foreach D,$(DISABLEDFFLIBS),$(eval $(call DODISABLEDSUBDIR,lib$(D))))
>
>  include $(SRC_PATH)/fftools/Makefile
>  include $(SRC_PATH)/doc/Makefile
> diff --git a/doc/Makefile b/doc/Makefile
> index 25774c7bad..d71a02e408 100644
> --- a/doc/Makefile
> +++ b/doc/Makefile
> @@ -100,7 +100,7 @@ doc/%.3: doc/%.pod $(GENTEXI)
>
>  $(DOCS) doc/doxy/html: | doc/
>
> -DOXY_INPUT      = $(INSTHEADERS)
> +DOXY_INPUT      = $(INSTHEADERS) $(DISABLEDINSTHEADERS)
>  DOXY_INPUT_DEPS = $(addprefix $(SRC_PATH)/, $(DOXY_INPUT)) ffbuild/config.mak
>
>  doc/doxy/html: TAG = DOXY
> -- 
> 2.37.0 (Apple Git-136)

Ping for review
Jan Ekström Nov. 24, 2022, 10 p.m. UTC | #4 
On Wed, Nov 16, 2022 at 7:21 PM Marvin Scholz <epirat07@gmail.com> wrote:
>
> On 24 Sep 2022, at 23:09, Marvin Scholz wrote:
>
> > Add DISABLEDINSTHEADERS, a variable containing the headers of disabled
> > libraries. This is needed so that Doxygen does not generate incomplete
> > documentation when a component is disabled, which is quite unexpected
> > behaviour and results in warnings due to, among other things, broken
> > references.
> > ---

I can get behind the idea of "always building the full docs,
especially if the documentation is otherwise broken.", thus +1 for the
idea behind the patch at least.

> >  Makefile     | 10 ++++++++++
> >  doc/Makefile |  2 +-
> >  2 files changed, 11 insertions(+), 1 deletion(-)
> >
> > diff --git a/Makefile b/Makefile
> > index 61f79e27ae..26714950b7 100644
> > --- a/Makefile
> > +++ b/Makefile
> > @@ -110,7 +110,17 @@ include $(SRC_PATH)/$(1)/Makefile
> >  include $(SRC_PATH)/ffbuild/library.mak
> >  endef
> >
> > +define DODISABLEDSUBDIR
> > +$(foreach V,$(SUBDIR_VARS),$(eval $(call RESET,$(V))))
> > +SUBDIR := $(1)/
> > +include $(SRC_PATH)/$(1)/Makefile

Now, I am not 100% sure what the effect of this inclusion is, so it'd
be nice if you could enlighten me. I see there are some unconditional
definitions in f.ex. libavcodec/Makefile (such as TESTPROGS), but
would those be still under the defined NAME (avcodec) or so, and thus
effectively not affect the build even where some unconditional
definitions exist in the included Makefile?

Do excuse me if there is a very similar inclusion for something not
enabled just outside of the patch diff context, thus noting that this
is completely OK :)

> > +DISABLEDINSTHEADERS := $$(DISABLEDINSTHEADERS) $$(HEADERS:%=$$(SUBDIR)%)
> > +endef
> > +
> > +DISABLEDFFLIBS := $(filter-out $(FFLIBS),$(ALLFFLIBS))
> > +
> >  $(foreach D,$(FFLIBS),$(eval $(call DOSUBDIR,lib$(D))))
> > +$(foreach D,$(DISABLEDFFLIBS),$(eval $(call DODISABLEDSUBDIR,lib$(D))))
> >
> >  include $(SRC_PATH)/fftools/Makefile
> >  include $(SRC_PATH)/doc/Makefile
> > diff --git a/doc/Makefile b/doc/Makefile
> > index 25774c7bad..d71a02e408 100644
> > --- a/doc/Makefile
> > +++ b/doc/Makefile
> > @@ -100,7 +100,7 @@ doc/%.3: doc/%.pod $(GENTEXI)
> >
> >  $(DOCS) doc/doxy/html: | doc/
> >
> > -DOXY_INPUT      = $(INSTHEADERS)
> > +DOXY_INPUT      = $(INSTHEADERS) $(DISABLEDINSTHEADERS)
> >  DOXY_INPUT_DEPS = $(addprefix $(SRC_PATH)/, $(DOXY_INPUT)) ffbuild/config.mak
> >
> >  doc/doxy/html: TAG = DOXY
> > --
> > 2.37.0 (Apple Git-136)
>
> Ping for review

Jan
diff mbox series

Patch

diff --git a/Makefile b/Makefile
index 61f79e27ae..26714950b7 100644
--- a/Makefile
+++ b/Makefile
@@ -110,7 +110,17 @@  include $(SRC_PATH)/$(1)/Makefile
 include $(SRC_PATH)/ffbuild/library.mak
 endef
 
+define DODISABLEDSUBDIR
+$(foreach V,$(SUBDIR_VARS),$(eval $(call RESET,$(V))))
+SUBDIR := $(1)/
+include $(SRC_PATH)/$(1)/Makefile
+DISABLEDINSTHEADERS := $$(DISABLEDINSTHEADERS) $$(HEADERS:%=$$(SUBDIR)%)
+endef
+
+DISABLEDFFLIBS := $(filter-out $(FFLIBS),$(ALLFFLIBS))
+
 $(foreach D,$(FFLIBS),$(eval $(call DOSUBDIR,lib$(D))))
+$(foreach D,$(DISABLEDFFLIBS),$(eval $(call DODISABLEDSUBDIR,lib$(D))))
 
 include $(SRC_PATH)/fftools/Makefile
 include $(SRC_PATH)/doc/Makefile
diff --git a/doc/Makefile b/doc/Makefile
index 25774c7bad..d71a02e408 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -100,7 +100,7 @@  doc/%.3: doc/%.pod $(GENTEXI)
 
 $(DOCS) doc/doxy/html: | doc/
 
-DOXY_INPUT      = $(INSTHEADERS)
+DOXY_INPUT      = $(INSTHEADERS) $(DISABLEDINSTHEADERS)
 DOXY_INPUT_DEPS = $(addprefix $(SRC_PATH)/, $(DOXY_INPUT)) ffbuild/config.mak
 
 doc/doxy/html: TAG = DOXY