Merge branch '3.0'

7 files changed, 259 insertions, 68 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index c9c29a92..dab41307 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -52,6 +52,11 @@
 #  Requires glib development package v2.20 or higher
 #  Default=true (build the libical-glib interface)
 #
+# -DENABLE_GTK_DOC=[true|false]
+#  Set to build libical-glib developer documentation
+#  Requires gtk-doc and ICAL_BUILD_DOCS option to be true.
+#  Default=true (build gtk-doc developer documentation)
+#
 # -DUSE_32BIT_TIME_T=[true|false]
 #  Set to build using a 32bit time_t (ignored unless building with MSVC on Windows)
 #  Default=false (use the default size of time_t)
diff --git a/Install.txt b/Install.txt
index 71fedff1..9df6cf3e 100644
--- a/Install.txt
+++ b/Install.txt
@@ -139,3 +139,4 @@ for example: cmake -DCMAKE_INSTALL_PREFIX=/opt -DCMAKE_INSTALL_LIBDIR=/opt/lib32
 == Build the documentation ==
 Run 'make docs' to build the API documentation and reference.
 Disable the docs make target by running CMake with -DICAL_BUILD_DOCS=False option.
+Disable the libical-glib developer documentation by running CMake with -DENABLE_GTK_DOC=False.
diff --git a/ReleaseNotes.txt b/ReleaseNotes.txt
index d78b1073..00d198de 100644
--- a/ReleaseNotes.txt
+++ b/ReleaseNotes.txt
@@ -16,6 +16,7 @@ Version 3.0.5 (NOT RELEASED YET):
 -------------
  * New publicly available function:
      + icalproperty_get_datetime_with_component()
+ * New CMake option ENABLE_GTK_DOC for disabling the libical-glib developer documentation
 
 Version 3.0.4:
 --------------
diff --git a/cmake/modules/GtkDoc.cmake b/cmake/modules/GtkDoc.cmake
new file mode 100644
index 00000000..32558701
--- /dev/null
+++ b/cmake/modules/GtkDoc.cmake
@@ -0,0 +1,239 @@
+# GtkDoc.cmake
+#
+# Macros to support develper documentation build from sources with gtk-doc.
+#
+# Note that every target and dependency should be defined before the macro is
+# called, because it uses information from those targets.
+#
+# add_gtkdoc(_module _namespace _deprecated_guards _srcdirsvar _depsvar _ignoreheadersvar)
+#    Adds rules to build developer documentation using gtk-doc for some part.
+#    Arguments:
+#       _module - the module name, like 'camel'; it expects ${_part}-docs.sgml.in in the CMAKE_CURRENT_SOURCE_DIR
+#       _namespace - namespace for symbols
+#       _deprecated_guards - define name, which guards deprecated symbols
+#       _srcdirsvar - variable with dirs where the source files are located
+#       _depsvar - a variable with dependencies (targets)
+#       _ignoreheadersvar - a variable with a set of header files to ignore
+#
+# It also adds custom target gtkdoc-rebuild-${_module}-sgml to rebuild the sgml.in
+# file based on the current sources.
+
+option(ENABLE_GTK_DOC "Use gtk-doc to build documentation" True)
+
+if(NOT ENABLE_GTK_DOC)
+  return()
+endif()
+
+find_program(GTKDOC_SCAN gtkdoc-scan)
+find_program(GTKDOC_SCANGOBJ gtkdoc-scangobj)
+find_program(GTKDOC_MKDB gtkdoc-mkdb)
+find_program(GTKDOC_MKHTML gtkdoc-mkhtml)
+find_program(GTKDOC_FIXXREF gtkdoc-fixxref)
+
+if(NOT (GTKDOC_SCAN AND GTKDOC_MKDB AND GTKDOC_MKHTML AND GTKDOC_FIXXREF))
+  message(FATAL_ERROR "Cannot find all gtk-doc binaries, install them or use -DENABLE_GTK_DOC=OFF  instead")
+  return()
+endif()
+
+if(NOT TARGET gtkdocs)
+  add_custom_target(gtkdocs ALL)
+endif()
+
+if(NOT TARGET gtkdoc-rebuild-sgmls)
+  add_custom_target(gtkdoc-rebuild-sgmls)
+endif()
+
+macro(add_gtkdoc _module _namespace _deprecated_guards _srcdirsvar _depsvar _ignoreheadersvar)
+  configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/${_module}-docs.sgml.in
+    ${CMAKE_CURRENT_BINARY_DIR}/${_module}-docs.sgml
+    @ONLY)
+
+  set(OUTPUT_DOCDIR ${SHARE_INSTALL_DIR}/gtk-doc/html/${_module})
+
+  set(_filedeps)
+  set(_srcdirs)
+  foreach(_srcdir ${${_srcdirsvar}})
+    set(_srcdirs ${_srcdirs} --source-dir="${_srcdir}")
+    file(GLOB _files ${_srcdir}/*.h* ${_srcdir}/*.c*)
+    list(APPEND _filedeps ${_files})
+  endforeach()
+
+  set(_mkhtml_prefix "")
+  if(APPLE)
+    set(_mkhtml_prefix "${CMAKE_COMMAND} -E env XML_CATALOG_FILES=\"/usr/local/etc/xml/catalog\"")
+  endif()
+
+  set(_scangobj_deps)
+  set(_scangobj_cflags_list)
+  set(_scangobj_cflags "")
+  set(_scangobj_ldflags "")
+  set(_scangobj_ld_lib_dirs "")
+
+  list(APPEND _scangobj_cflags_list -I${INCLUDE_INSTALL_DIR})
+  list(APPEND _scangobj_ldflags -L${LIB_INSTALL_DIR})
+
+  foreach(opt IN LISTS ${_depsvar})
+    if(TARGET ${opt})
+      set(_target_type)
+      get_target_property(_target_type ${opt} TYPE)
+      if((_target_type STREQUAL "STATIC_LIBRARY") OR (_target_type STREQUAL "SHARED_LIBRARY") OR (_target_type STREQUAL "MODULE_LIBRARY"))
+        set(_compile_options)
+        set(_link_libraries)
+
+        get_target_property(_compile_options ${opt} COMPILE_OPTIONS)
+        get_target_property(_link_libraries ${opt} LINK_LIBRARIES)
+
+        list(APPEND _scangobj_cflags_list ${_compile_options})
+        list(APPEND _scangobj_deps ${_link_libraries})
+
+        unset(_compile_options)
+        unset(_link_libraries)
+      endif()
+      unset(_target_type)
+    endif()
+
+    list(APPEND _scangobj_deps ${opt})
+  endforeach()
+
+  if(_scangobj_deps)
+    list(REMOVE_DUPLICATES _scangobj_deps)
+  endif()
+  if(_scangobj_cflags_list)
+    list(REMOVE_DUPLICATES _scangobj_cflags_list)
+  endif()
+
+  foreach(opt IN LISTS _scangobj_cflags_list)
+    set(_scangobj_cflags "${_scangobj_cflags} ${opt}")
+  endforeach()
+
+  foreach(opt IN LISTS _scangobj_deps)
+    if(TARGET ${opt})
+      set(_target_type)
+      get_target_property(_target_type ${opt} TYPE)
+      if((_target_type STREQUAL "STATIC_LIBRARY") OR (_target_type STREQUAL "SHARED_LIBRARY") OR (_target_type STREQUAL "MODULE_LIBRARY"))
+        set(_output_name "")
+        get_target_property(_output_name ${opt} OUTPUT_NAME)
+        if(NOT _output_name)
+          set(_output_name ${opt})
+        endif()
+        set(_scangobj_ldflags "${_scangobj_ldflags} -L$<TARGET_FILE_DIR:${opt}> -l${_output_name}")
+
+        if(_target_type STREQUAL "SHARED_LIBRARY" OR (_target_type STREQUAL "MODULE_LIBRARY"))
+          set(_scangobj_ld_lib_dirs "${_scangobj_ld_lib_dirs}:$<TARGET_FILE_DIR:${opt}>")
+        endif()
+        unset(_output_name)
+      endif()
+      unset(_target_type)
+    else()
+      set(_scangobj_ldflags "${_scangobj_ldflags} ${opt}")
+    endif()
+  endforeach()
+
+  set(_scangobj_prefix ${CMAKE_COMMAND} -E env LD_LIBRARY_PATH="${_scangobj_ld_lib_dirs}:${LIB_INSTALL_DIR}")
+
+  if(NOT (_scangobj_cflags STREQUAL ""))
+    set(_scangobj_cflags --cflags "${_scangobj_cflags}")
+  endif()
+
+  if(NOT (_scangobj_ldflags STREQUAL ""))
+    set(_scangobj_ldflags --ldflags "${_scangobj_ldflags}")
+  endif()
+
+  add_custom_command(OUTPUT html/index.html
+    COMMAND ${GTKDOC_SCAN}
+      --module=${_module}
+      --deprecated-guards="${_deprecated_guards}"
+      --ignore-headers="${${_ignoreheadersvar}}"
+      --rebuild-sections
+      --rebuild-types
+      ${_srcdirs}
+
+    COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}" ${_scangobj_prefix} ${GTKDOC_SCANGOBJ}
+      --module=${_module}
+      ${_scangobj_cflags}
+      ${_scangobj_ldflags}
+
+    COMMAND ${GTKDOC_MKDB}
+      --module=${_module}
+      --name-space=${_namespace}
+      --main-sgml-file="${CMAKE_CURRENT_BINARY_DIR}/${_module}-docs.sgml"
+      --sgml-mode
+      --output-format=xml
+      ${_srcdirs}
+
+    COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/html"
+
+    COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}/html" ${_mkhtml_prefix} ${GTKDOC_MKHTML} --path=.. ${_module} ../${_module}-docs.sgml
+
+    COMMAND ${GTKDOC_FIXXREF}
+      --module=${_module}
+      --module-dir=html
+      --extra-dir=..
+      --html-dir="${OUTPUT_DOCDIR}"
+
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/${_module}-docs.sgml"
+      ${_filedeps}
+    COMMENT "Generating ${_module} documentation"
+  )
+
+  add_custom_target(gtkdoc-${_module}
+    DEPENDS html/index.html
+  )
+
+  if(${_depsvar})
+    add_dependencies(gtkdoc-${_module} ${${_depsvar}})
+  endif(${_depsvar})
+
+  add_dependencies(gtkdocs gtkdoc-${_module})
+
+  install(
+    DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/
+    DESTINATION ${OUTPUT_DOCDIR}
+  )
+
+  # ***************************************
+  # sgml.in file rebuild, unconditional
+  # ***************************************
+  add_custom_target(gtkdoc-rebuild-${_module}-sgml
+    COMMAND ${CMAKE_COMMAND} -E remove_directory "${CMAKE_CURRENT_BINARY_DIR}/tmp"
+    COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/tmp"
+
+    COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}/tmp"
+      ${GTKDOC_SCAN}
+      --module=${_module}
+      --deprecated-guards="${_deprecated_guards}"
+      --ignore-headers="${_ignore_headers}"
+      --rebuild-sections
+      --rebuild-types
+      ${_srcdirs}
+
+    COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}" ${_scangobj_prefix} ${GTKDOC_SCANGOBJ}
+      --module=${_module}
+      ${_scangobj_cflags}
+      ${_scangobj_ldflags}
+
+    COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}/tmp"
+      ${GTKDOC_MKDB}
+      --module=${_module}
+      --name-space=${_namespace}
+      --main-sgml-file="${CMAKE_CURRENT_BINARY_DIR}/tmp/${_module}-docs.sgml"
+      --sgml-mode
+      --output-format=xml
+      ${_srcdirs}
+
+    COMMAND ${CMAKE_COMMAND} -E rename ${CMAKE_CURRENT_BINARY_DIR}/tmp/${_module}-docs.sgml ${CMAKE_CURRENT_SOURCE_DIR}/${_module}-docs.sgml.in
+
+    COMMAND ${CMAKE_COMMAND} -E echo "File '${CMAKE_CURRENT_SOURCE_DIR}/${_module}-docs.sgml.in' overwritten, make sure you replace generated strings with proper content before committing."
+  )
+
+  add_dependencies(gtkdoc-rebuild-sgmls gtkdoc-rebuild-${_module}-sgml)
+
+  unset(_scangobj_prefix)
+  unset(_scangobj_deps)
+  unset(_scangobj_cflags_list)
+  unset(_scangobj_cflags)
+  unset(_scangobj_ldflags)
+  unset(_scangobj_ld_lib_dirs)
+endmacro()
diff --git a/doc/reference/libical-glib/CMakeLists.txt b/doc/reference/libical-glib/CMakeLists.txt
index 4013d570..ca58244c 100644
--- a/doc/reference/libical-glib/CMakeLists.txt
+++ b/doc/reference/libical-glib/CMakeLists.txt
@@ -1,12 +1,4 @@
-find_program(GTKDOC_SCAN gtkdoc-scan DOC "a tool to scan header files for public symbols")
-find_program(GTKDOC_MKDB gtkdoc-mkdb DOC "a tool to generate docbook files")
-find_program(GTKDOC_MKHTML gtkdoc-mkhtml DOC "a tool to generate documentation in html format")
-find_program(GTKDOC_FIXXREF gtkdoc-fixxref DOC "a tool to fix cross references in html files")
-
-if(NOT (GTKDOC_SCAN AND GTKDOC_MKDB AND GTKDOC_MKHTML AND GTKDOC_FIXXREF))
-  message(WARNING "Cannot find all gtk-doc binaries, skipping API reference generation for libical-glib")
-  return()
-endif()
+include(GtkDoc)
 
 # To regenerate libical-glib-docs.xml.in from current sources use these steps:
 #   a) delete ${CMAKE_CURRENT_BINARY_DIR}/libical-glib-docs.xml
@@ -22,67 +14,20 @@ endif()
 #   e) compare the changes in the file and return back what should be left,
 #      like the replacement of the "[Insert title here]" and the <bookinfo/> content
 
-configure_file(
-  ${CMAKE_CURRENT_SOURCE_DIR}/libical-glib-docs.xml.in
-  ${CMAKE_CURRENT_BINARY_DIR}/libical-glib-docs.xml
-  @ONLY
-)
-
-set(OUTPUT_DOCDIR ${SHARE_INSTALL_DIR}/gtk-doc/html/libical-glib)
-
-add_custom_command(OUTPUT xml/libical-glib-doc.bottom
-  COMMAND ${GTKDOC_SCAN} --module=libical-glib
-    --source-dir="${CMAKE_BINARY_DIR}/src/libical-glib"
-    --deprecated-guards="LIBICAL_GLIB_DISABLE_DEPRECATED"
-    --ignore-headers=libical-glib-private.h
-    --rebuild-sections
-    --rebuild-types
+if(ENABLE_GTK_DOC)
 
-  COMMAND ${GTKDOC_MKDB}
-    --module=libical-glib
-    --name-space=i-cal
-    --main-sgml-file="${CMAKE_CURRENT_BINARY_DIR}/libical-glib-docs.xml"
-    --xml-mode
-    --output-format=xml
-    --source-dir="${CMAKE_BINARY_DIR}/src/libical-glib"
-    COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/html"
-    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/libical-glib-docs.xml"
-)
-
-if(APPLE)
-  add_custom_command(OUTPUT html/index.html
-    COMMAND env XML_CATALOG_FILES="/usr/local/etc/xml/catalog" ${GTKDOC_MKHTML}
-      --path=..
-      libical-glib
-      ../libical-glib-docs.xml
-    WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html"
-    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/libical-glib-docs.xml"
-            "${CMAKE_CURRENT_BINARY_DIR}/xml/libical-glib-doc.bottom"
-    COMMENT "Generating libical-glib documentation"
+  set(SOURCEDIRS
+    ${CMAKE_BINARY_DIR}/src/libical-glib
   )
-else()
-  add_custom_command(OUTPUT html/index.html
-    COMMAND ${GTKDOC_MKHTML}
-      --path=..
-      libical-glib
-      ../libical-glib-docs.xml
-    WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html"
-    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/libical-glib-docs.xml"
-            "${CMAKE_CURRENT_BINARY_DIR}/xml/libical-glib-doc.bottom"
-    COMMENT "Generating libical-glib documentation"
+
+  set(DEPENDENCIES
+    ical-glib
   )
-endif()
 
-add_custom_target(documentation ALL
-  COMMAND ${GTKDOC_FIXXREF}
-    --module=libical-glib
-    --module-dir=.
-    --extra-dir=..
-    --html-dir=${OUTPUT_DOCDIR}
-  DEPENDS html/index.html
-  COMMENT "Generating libical-glib documentation"
+  set(IGNORE_HEADERS
+    libical-glib-private.h
   )
 
-add_dependencies(documentation ical-glib)
+  add_gtkdoc(libical-glib libical-glib "LIBICAL_GLIB_DISABLE_DEPRECATED" SOURCEDIRS DEPENDENCIES IGNORE_HEADERS)
 
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ DESTINATION ${OUTPUT_DOCDIR})
+endif()
diff --git a/doc/reference/libical-glib/libical-glib-docs.xml.in b/doc/reference/libical-glib/libical-glib-docs.sgml.in
index b202e198..b202e198 100644
--- a/doc/reference/libical-glib/libical-glib-docs.xml.in
+++ b/doc/reference/libical-glib/libical-glib-docs.sgml.in
diff --git a/scripts/buildtests.sh b/scripts/buildtests.sh
index 2fb99fd5..b05b3922 100755
--- a/scripts/buildtests.sh
+++ b/scripts/buildtests.sh
@@ -89,7 +89,7 @@ CHECK_WARNINGS() {
 # print warnings found in the compile-stage output
 # $1 = file with the compile-stage output
 COMPILE_WARNINGS() {
-  whitelist='\(Value[[:space:]]descriptions\|unused[[:space:]]declarations\|g-ir-scanner:\|clang.*argument[[:space:]]unused[[:space:]]during[[:space:]]compilation\|U_PLATFORM_HAS_WINUWP_API\|DB_DBM_HSEARCH\|const[[:space:]]DBT\|db\.h\)'
+  whitelist='\(no[[:space:]]link[[:space:]]for:\|Value[[:space:]]descriptions\|unused[[:space:]]declarations\|g-ir-scanner:\|clang.*argument[[:space:]]unused[[:space:]]during[[:space:]]compilation\|U_PLATFORM_HAS_WINUWP_API\|DB_DBM_HSEARCH\|const[[:space:]]DBT\|db\.h\)'
   CHECK_WARNINGS $1 "warning:" "$whitelist"
 }
 
@@ -112,7 +112,7 @@ TIDY_WARNINGS() {
 # print warnings found in the scan-build output
 # $1 = file with the scan-build output
 SCAN_WARNINGS() {
-  whitelist='\(Value[[:space:]]descriptions\|unused[[:space:]]declarations\|icalerror.*Dereference[[:space:]]of[[:space:]]null[[:space:]]pointer\)'
+  whitelist='\(no[[:space:]]link[[:space:]]for:\|Value[[:space:]]descriptions\|unused[[:space:]]declarations\|icalerror.*Dereference[[:space:]]of[[:space:]]null[[:space:]]pointer\)'
   CHECK_WARNINGS $1 "warning:" "$whitelist"
 }