[geos-devel] [GEOS] #988: Doxygen error check with cmake build

[GEOS]

#988: Doxygen error check with cmake build
-----------------------------------+---------------------------
 Reporter:  nila                   |       Owner:  geos-devel@…
     Type:  enhancement            |      Status:  new
 Priority:  major                  |   Milestone:
Component:  Build/Install (cmake)  |     Version:  master
 Severity:  Unassigned             |  Resolution:
 Keywords:                         |
-----------------------------------+---------------------------

Comment (by nila):

 As I suspected @strk, but didn't want to put words in your mouth. And I
 agree. Better to keep all warnings in logfile, what's hidden is forgotten.
 I made a small change in the error check cmake-script, which states in
 build log how many warnings had been issued:
 e.g.

 {{{-- Doxygen issued 1702 warning(s), see
 /home/travis/build/libgeos/geos/_build/doc/doxygen.log}}}

 regardless if the build succeeds or not.

 I've tested reverting the Doxygen.in file to version 1.8.8, and setting
 WARN_IF_UNDOCUMENTED to NO. Building with 1.8.15 didn't issue any
 warnings, so this could be a way to go, but in the future obsolete tags
 might appear as well, so... For now, I think we should decide what
 warnings we can allow to be ignored.

 @dbaston I opened a PR on github as well
 [https://github.com/libgeos/geos/pull/224], with intentional doxygen
 errors and the {{{doxygen-checked}}} target activated on travis, and the
 build failed as expected:

 {{{
 Built target docs
 Scanning dependencies of target doxygen-checked
 -- Doxygen issued 1702 warning(s), see
 /home/travis/build/libgeos/geos/_build/doc/doxygen.log
 CMake Error at check_doxygen_errors.cmake:42 (message):
   /home/travis/build/libgeos/geos/include/geos/noding/SegmentNode.h:70:
   warning: argument 'THISISCOMPLETELYWRONGTOO' of command @param is not
 found
   in the argument list of geos::noding::SegmentNode::SegmentNode(const
   NodedSegmentString &ss, const geom::Coordinate &nCoord, size_t
   nSegmentIndex, int nSegmentOctant)

   /home/travis/build/libgeos/geos/include/geos/planargraph/Edge.h:88:
   warning: argument 'THISISCOMPLETELYWRONG' of command @param is not found
 in
   the argument list of geos::planargraph::Edge::Edge(DirectedEdge *de0,
   DirectedEdge *de1)

     parameter 'de0'
     parameter 'de1'


 doc/CMakeFiles/doxygen-checked.dir/build.make:57: recipe for target
 'doc/CMakeFiles/doxygen-checked' failed
 make[3]: *** [doc/CMakeFiles/doxygen-checked] Error 1
 CMakeFiles/Makefile2:1888: recipe for target 'doc/CMakeFiles/doxygen-
 checked.dir/all' failed
 make[2]: *** [doc/CMakeFiles/doxygen-checked.dir/all] Error 2
 CMakeFiles/Makefile2:1895: recipe for target 'doc/CMakeFiles/doxygen-
 checked.dir/rule' failed
 make[1]: *** [doc/CMakeFiles/doxygen-checked.dir/rule] Error 2
 Makefile:795: recipe for target 'doxygen-checked' failed
 make: *** [doxygen-checked] Error 2
 The command "./tools/ci/script.sh" exited with 2.
 }}}

 Now, it should be tested on Windows too (I've tested on macOS). @dbaston,
 could you please help out with this?

-- 
Ticket URL: <https://trac.osgeo.org/geos/ticket/988#comment:4>
GEOS <http://trac.osgeo.org/geos>
GEOS (Geometry Engine - Open Source) is a C++ port of the Java Topology Suite (JTS).