Commit 438ec699 authored by Jonathan Michalon's avatar Jonathan Michalon

Fix/workaround doc issues (warnings, gtkdoc requirement, .PHONY html)

parent 544aa2be
......@@ -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])
])
......@@ -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
  • out of curiosity, why the change? I agree it's a probably better naming, but I'm wondering if there's another reason for this change?

  • Because "html" is a target for texinfo in automake, and as such get always appended as .PHONY, thus ours get always re-run even if not needed.

  • oh, ok, makes sense

Please register or sign in to reply
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 $@
  • do we really need an empty dir!?

  • Could be an empty file to fullfill the target or whatever but I thought it would be confusing ie. for packaging afterwards that sometimes we get a dir, sometimes a file, … Best would probably be to disable completely the rule but not sure either if it's practical to have stuff disappearing completely. Empty dir sounds to me like "yeah we know but right now still no possible" :D

  • ah yeah if we need something, makes sense. But I think it's best nothing gets done at all if it's not enabled.

Please register or sign in to reply
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:
  • what about just adding uninstall-doc-gtkdoc to uninstall-hook conditionally?

  • And then, the build target gtkdoc: itself too? I'm not against, see previous comment.

Please register or sign in to reply
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:
Please register or sign in to reply
endif
uninstall-hook: uninstall-doc-devhelp uninstall-doc-gtkdoc
......
......@@ -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();
Please register or sign in to reply
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);
}
}
}
......
......@@ -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... ||
  • haha :D is that the real syntax, or just a not-so-bad-looking hack?

  • Real syntax, rendering pretty bad on the page but still… see Tables here: https://valadoc.org/markup.htm

  • Nah I meant for documenting enums. I figured it was the table syntax, but didn't expect this was how valadoc wanted enums documented.

  • Ah, then, no. I couldn't find a project where enums were documented at all even in libvala… the only places I found where valadoc generates something nice is when imported from other non-valadoc sources…

Please register or sign in to reply
*/
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
......
......@@ -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])
])
......@@ -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
......
......@@ -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)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment