From 438ec6994711371501c381f1c259065b676ce3b1 Mon Sep 17 00:00:00 2001 From: Jonathan Michalon Date: Sat, 18 May 2019 11:47:17 +0200 Subject: [PATCH] Fix/workaround doc issues (warnings, gtkdoc requirement, .PHONY html) --- libovcc/build/ovcc-valadoc.m4 | 5 ++++ libovcc/build/ovcc-valadoc.make | 35 ++++++++++++++++-------- libovcc/src/ovcc-board.vala | 10 +++---- libovcc/src/ovcc-game.vala | 18 ++++++------ libovccclient/build/ovcc-valadoc.m4 | 5 ++++ libovccclient/build/ovcc-valadoc.make | 35 ++++++++++++++++-------- libovccclient/src/ovccclient-server.vala | 14 +++++----- 7 files changed, 79 insertions(+), 43 deletions(-) diff --git a/libovcc/build/ovcc-valadoc.m4 b/libovcc/build/ovcc-valadoc.m4 index 9071339..35b0ba4 100644 --- a/libovcc/build/ovcc-valadoc.m4 +++ b/libovcc/build/ovcc-valadoc.m4 @@ -29,4 +29,9 @@ AC_DEFUN([OVCC_VALADOC_CHECK], [AS_IF([test "x$enable_valadoc" = xyes], [AC_MSG_ERROR([valadoc not found or too old])])])]) AM_CONDITIONAL([ENABLE_VALADOC], [test "x$have_valadoc" = xyes]) + + # check for gtkdoc needed by gtkdoc doclet + AS_IF([test "x$have_valadoc" = xyes], + [AC_PATH_PROG([GTKDOC], [gtkdoc-scan], [NONE])]) + AM_CONDITIONAL([ENABLE_VALADOC_GTKDOC], [test "x$GTKDOC" != xNONE]) ]) diff --git a/libovcc/build/ovcc-valadoc.make b/libovcc/build/ovcc-valadoc.make index cbcf830..3d85da5 100644 --- a/libovcc/build/ovcc-valadoc.make +++ b/libovcc/build/ovcc-valadoc.make @@ -19,10 +19,10 @@ valadoc_real_flags = --no-protected \ --package-version $(VALADOC_MODULE_VERSION) \ $(VALADOC_FILES) -EXTRA_DIST = html devhelp gtkdoc +EXTRA_DIST = valadoc devhelp gtkdoc -doc: html devhelp gtkdoc -dist-hook: html devhelp gtkdoc +doc: valadoc devhelp gtkdoc +dist-hook: valadoc devhelp gtkdoc # Removing the target before building the documentation avoids conflicts # between doclet and directory names, since valadoc first tries to find the @@ -30,32 +30,37 @@ dist-hook: html devhelp gtkdoc # For the gtkdoc doclet, it also prevents leftover files to be used and # produce wrong results, e.g. if a file got renamed. -html: $(VALADOC_FILES) - $(RM) -r $@ - $(VALADOC) \ +valadoc: $(VALADOC_FILES) + $(AM_V_at)$(RM) -r $@ + $(AM_V_GEN)$(VALADOC) \ -o $@ \ --doclet html \ $(valadoc_real_flags) devhelp: $(VALADOC_FILES) - $(RM) -r $@ - $(VALADOC) \ + $(AM_V_at)$(RM) -r $@ + $(AM_V_GEN)$(VALADOC) \ -o $@ \ --doclet devhelp \ $(valadoc_real_flags) +if ENABLE_VALADOC_GTKDOC gtkdoc: $(VALADOC_FILES) - $(RM) -r $@ - $(VALADOC) \ + $(AM_V_at)$(RM) -r $@ + $(AM_V_GEN)$(VALADOC) \ -X -l -X $(VALADOC_LIB) \ -X $(VALADOC_CHEADER) \ -o $@ \ --doclet gtkdoc \ $(valadoc_real_flags) +else +gtkdoc: + $(AM_V_at)mkdir $@ +endif clean-local: - $(RM) -r html devhelp gtkdoc + $(RM) -r valadoc devhelp gtkdoc uninstall-doc-devhelp: $(RM) -r $(DESTDIR)$(datadir)/devhelp/books/$(VALADOC_MODULE_NAME) @@ -65,12 +70,20 @@ install-doc-devhelp: devhelp $(INSTALL_DATA) -t $(DESTDIR)$(datadir)/devhelp/books/$(VALADOC_MODULE_NAME) devhelp/$(VALADOC_MODULE_NAME)/*.* $(INSTALL_DATA) -t $(DESTDIR)$(datadir)/devhelp/books/$(VALADOC_MODULE_NAME)/img devhelp/$(VALADOC_MODULE_NAME)/img/* +if ENABLE_VALADOC_GTKDOC uninstall-doc-gtkdoc: $(RM) -r $(DESTDIR)$(datadir)/gtk-doc/html/$(VALADOC_MODULE_NAME) +else +uninstall-doc-gtkdoc: +endif +if ENABLE_VALADOC_GTKDOC install-doc-gtkdoc: gtkdoc $(MKDIR_P) $(DESTDIR)$(datadir)/gtk-doc/html/$(VALADOC_MODULE_NAME) $(INSTALL_DATA) -t $(DESTDIR)$(datadir)/gtk-doc/html/$(VALADOC_MODULE_NAME) gtkdoc/html/*.* +else +install-doc-gtkdoc: +endif uninstall-hook: uninstall-doc-devhelp uninstall-doc-gtkdoc diff --git a/libovcc/src/ovcc-board.vala b/libovcc/src/ovcc-board.vala index 19eea82..2f5da90 100644 --- a/libovcc/src/ovcc-board.vala +++ b/libovcc/src/ovcc-board.vala @@ -168,12 +168,12 @@ namespace OVCC /** * Checks whether a tile is placeable on the board * - * @param tile a tile + * @param tile a {@link tile} * @return true if the tile can be placed, false otherwise. */ - public bool is_tile_placeable (Tile t) + public bool is_tile_placeable (Tile tile) { - var tile = t.dup(); + var tiledup = tile.dup(); return false == this.foreach ((b, p, t) => { for (var i = 0; i < 4; i++) { var npos = p; @@ -185,10 +185,10 @@ namespace OVCC case 3: npos.x--; break; /* left */ } for (var j = 0; j < 4; j++) { - if (this.add_tile_check (tile, npos)) { + if (this.add_tile_check (tiledup, npos)) { return false; } else { - tile.rotate (1); + tiledup.rotate (1); } } } diff --git a/libovcc/src/ovcc-game.vala b/libovcc/src/ovcc-game.vala index 3b9c2f3..f335d45 100644 --- a/libovcc/src/ovcc-game.vala +++ b/libovcc/src/ovcc-game.vala @@ -23,10 +23,10 @@ namespace OVCC /** * The errors of the GameError domain. * - * @param STARTED The game is started and the action therefore cannot be done. - * @param PLAYER_ALREADY_ADDED Player is already on the game. - * @param DUPLICATED_NICK Player have the same nick than an another player. - * @param FAILED Something failed... + * || STARTED || The game is started and the action therefore cannot be done. || + * || PLAYER_ALREADY_ADDED || Player is already on the game. || + * || DUPLICATED_NICK || Player have the same nick than an another player. || + * || FAILED || Something failed... || */ public errordomain GameError { @@ -40,11 +40,11 @@ namespace OVCC * Possible states of a game. * Only one state at a time. "Flags" type is used for filtering only. * - * @param NEW The game is just created but no player joined - * @param PLAYER_WAITING The game has players but is not started yet - * @param STARTED The game is started - * @param FINISHED The game is finished - * @param ABORTED The game is stopped, but not finished + * || NEW || The game is just created but no player joined || + * || PLAYER_WAITING || The game has players but is not started yet || + * || STARTED || The game is started || + * || FINISHED || The game is finished || + * || ABORTED || The game is stopped, but not finished || */ [Flags] public enum GameState diff --git a/libovccclient/build/ovcc-valadoc.m4 b/libovccclient/build/ovcc-valadoc.m4 index 9071339..35b0ba4 100644 --- a/libovccclient/build/ovcc-valadoc.m4 +++ b/libovccclient/build/ovcc-valadoc.m4 @@ -29,4 +29,9 @@ AC_DEFUN([OVCC_VALADOC_CHECK], [AS_IF([test "x$enable_valadoc" = xyes], [AC_MSG_ERROR([valadoc not found or too old])])])]) AM_CONDITIONAL([ENABLE_VALADOC], [test "x$have_valadoc" = xyes]) + + # check for gtkdoc needed by gtkdoc doclet + AS_IF([test "x$have_valadoc" = xyes], + [AC_PATH_PROG([GTKDOC], [gtkdoc-scan], [NONE])]) + AM_CONDITIONAL([ENABLE_VALADOC_GTKDOC], [test "x$GTKDOC" != xNONE]) ]) diff --git a/libovccclient/build/ovcc-valadoc.make b/libovccclient/build/ovcc-valadoc.make index cbcf830..3d85da5 100644 --- a/libovccclient/build/ovcc-valadoc.make +++ b/libovccclient/build/ovcc-valadoc.make @@ -19,10 +19,10 @@ valadoc_real_flags = --no-protected \ --package-version $(VALADOC_MODULE_VERSION) \ $(VALADOC_FILES) -EXTRA_DIST = html devhelp gtkdoc +EXTRA_DIST = valadoc devhelp gtkdoc -doc: html devhelp gtkdoc -dist-hook: html devhelp gtkdoc +doc: valadoc devhelp gtkdoc +dist-hook: valadoc devhelp gtkdoc # Removing the target before building the documentation avoids conflicts # between doclet and directory names, since valadoc first tries to find the @@ -30,32 +30,37 @@ dist-hook: html devhelp gtkdoc # For the gtkdoc doclet, it also prevents leftover files to be used and # produce wrong results, e.g. if a file got renamed. -html: $(VALADOC_FILES) - $(RM) -r $@ - $(VALADOC) \ +valadoc: $(VALADOC_FILES) + $(AM_V_at)$(RM) -r $@ + $(AM_V_GEN)$(VALADOC) \ -o $@ \ --doclet html \ $(valadoc_real_flags) devhelp: $(VALADOC_FILES) - $(RM) -r $@ - $(VALADOC) \ + $(AM_V_at)$(RM) -r $@ + $(AM_V_GEN)$(VALADOC) \ -o $@ \ --doclet devhelp \ $(valadoc_real_flags) +if ENABLE_VALADOC_GTKDOC gtkdoc: $(VALADOC_FILES) - $(RM) -r $@ - $(VALADOC) \ + $(AM_V_at)$(RM) -r $@ + $(AM_V_GEN)$(VALADOC) \ -X -l -X $(VALADOC_LIB) \ -X $(VALADOC_CHEADER) \ -o $@ \ --doclet gtkdoc \ $(valadoc_real_flags) +else +gtkdoc: + $(AM_V_at)mkdir $@ +endif clean-local: - $(RM) -r html devhelp gtkdoc + $(RM) -r valadoc devhelp gtkdoc uninstall-doc-devhelp: $(RM) -r $(DESTDIR)$(datadir)/devhelp/books/$(VALADOC_MODULE_NAME) @@ -65,12 +70,20 @@ install-doc-devhelp: devhelp $(INSTALL_DATA) -t $(DESTDIR)$(datadir)/devhelp/books/$(VALADOC_MODULE_NAME) devhelp/$(VALADOC_MODULE_NAME)/*.* $(INSTALL_DATA) -t $(DESTDIR)$(datadir)/devhelp/books/$(VALADOC_MODULE_NAME)/img devhelp/$(VALADOC_MODULE_NAME)/img/* +if ENABLE_VALADOC_GTKDOC uninstall-doc-gtkdoc: $(RM) -r $(DESTDIR)$(datadir)/gtk-doc/html/$(VALADOC_MODULE_NAME) +else +uninstall-doc-gtkdoc: +endif +if ENABLE_VALADOC_GTKDOC install-doc-gtkdoc: gtkdoc $(MKDIR_P) $(DESTDIR)$(datadir)/gtk-doc/html/$(VALADOC_MODULE_NAME) $(INSTALL_DATA) -t $(DESTDIR)$(datadir)/gtk-doc/html/$(VALADOC_MODULE_NAME) gtkdoc/html/*.* +else +install-doc-gtkdoc: +endif uninstall-hook: uninstall-doc-devhelp uninstall-doc-gtkdoc diff --git a/libovccclient/src/ovccclient-server.vala b/libovccclient/src/ovccclient-server.vala index c34aca3..951de01 100644 --- a/libovccclient/src/ovccclient-server.vala +++ b/libovccclient/src/ovccclient-server.vala @@ -101,14 +101,14 @@ namespace OVCCClient /** * A signal emitted when a message was received from server * - * @param msg A {@link Message} instance containing what the server sent us + * @param msg A {@link OVCC.Network.Message} instance containing what the server sent us */ [Signal (detailed = true)] public signal void message_received (Message msg); /** * A signal emitted when a message in queue was sent to the server * - * @param msg A {@link Message} instance which was just sent to the server + * @param msg A {@link OVCC.Network.Message} instance which was just sent to the server * @param err An optional error raised when sending */ public signal void message_sent (Message msg, @@ -210,10 +210,10 @@ namespace OVCCClient } /** - * Asynchronous method allowing to pause until a given {@link MessageType} + * Asynchronous method allowing to pause until a given {@link OVCC.Network.MessageType} * get received. * - * @param mtype The {@link MessageType} to wait for + * @param mtype The {@link OVCC.Network.MessageType} to wait for * @param cancellable a Cancellable object or null * @return The message received */ @@ -252,7 +252,7 @@ namespace OVCCClient /** * Asynchronous method to send messages to the remote server. * - * @param msg The {@link Message} to send + * @param msg The {@link OVCC.Network.Message} to send * @param cancellable a Cancellable object or null * @return Whether the operation succeeded. */ @@ -418,8 +418,8 @@ namespace OVCCClient * This method retrieves a list of available games currently on the server * matching the given filter * - * @param a mask of {@link GameState}s to filter in - * @return A list of {@link GameDescription} on the remote server matching //filter// + * @param filter a mask of {@link OVCC.GameState}s to filter in + * @return A list of {@link OVCC.GameDescription} on the remote server matching //filter// */ public async GameDescription[]? enumerate_games (GameState? filter = null, Cancellable? cancellable = null) -- GitLab