From 58b9f4eba6bf3bf39350e4c0a9005336cf1b61fc Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sat, 13 Jun 2020 23:22:44 +0200 Subject: [PATCH] Doc building: fix warnings when using recent Doxygen and/or Sphinx+Breathe (fixes #2673) --- gdal/Doxyfile | 7 +++- gdal/gcore/gdal.h | 18 ++++++-- gdal/gcore/gdal_priv.h | 7 +--- gdal/ogr/ogr_geometry.h | 87 ++++++++++++++++++++++++++++++++++++++- gdal/ogr/ogr_spatialref.h | 23 +++++++++-- gdal/port/cpl_conv.h | 2 +- 6 files changed, 129 insertions(+), 15 deletions(-) diff --git a/gdal/Doxyfile b/gdal/Doxyfile index e7afd116860..aedffa2e5f7 100644 --- a/gdal/Doxyfile +++ b/gdal/Doxyfile @@ -954,7 +954,12 @@ PREDEFINED = HAVE_DLFCN_H \ HAVE_LONG_LONG=1 \ HAVE_SC_PHYS_PAGES=1 \ final= \ - CPL_RESTRICT= + CPL_RESTRICT= \ + CPL_WARN_UNUSED_RESULT= \ + CPL_RETURNS_NONNULL= \ + CPLSTRING_METHOD_DLL= \ + CPL_NO_RETURN= \ + EXPERIMENTAL_CPL_WARN_UNUSED_RESULT= # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/gdal/gcore/gdal.h b/gdal/gcore/gdal.h index 7a232ee6278..0529d178ce2 100644 --- a/gdal/gcore/gdal.h +++ b/gdal/gcore/gdal.h @@ -956,7 +956,11 @@ CPLErr CPL_DLL CPL_STDCALL GDALGetRasterHistogram( GDALRasterBandH hBand, int nBuckets, int *panHistogram, int bIncludeOutOfRange, int bApproxOK, GDALProgressFunc pfnProgress, - void * pProgressData ) CPL_WARN_DEPRECATED("Use GDALGetRasterHistogramEx() instead"); + void * pProgressData ) +/*! @cond Doxygen_Suppress */ + CPL_WARN_DEPRECATED("Use GDALGetRasterHistogramEx() instead") +/*! @endcond */ + ; CPLErr CPL_DLL CPL_STDCALL GDALGetRasterHistogramEx( GDALRasterBandH hBand, double dfMin, double dfMax, int nBuckets, GUIntBig *panHistogram, @@ -968,7 +972,11 @@ CPLErr CPL_DLL CPL_STDCALL GDALGetDefaultHistogram( GDALRasterBandH hBand, int *pnBuckets, int **ppanHistogram, int bForce, GDALProgressFunc pfnProgress, - void * pProgressData ) CPL_WARN_DEPRECATED("Use GDALGetDefaultHistogramEx() instead"); + void * pProgressData ) +/*! @cond Doxygen_Suppress */ + CPL_WARN_DEPRECATED("Use GDALGetDefaultHistogramEx() instead") +/*! @endcond */ + ; CPLErr CPL_DLL CPL_STDCALL GDALGetDefaultHistogramEx( GDALRasterBandH hBand, double *pdfMin, double *pdfMax, int *pnBuckets, GUIntBig **ppanHistogram, @@ -977,7 +985,11 @@ CPLErr CPL_DLL CPL_STDCALL GDALGetDefaultHistogramEx( GDALRasterBandH hBand, void * pProgressData ); CPLErr CPL_DLL CPL_STDCALL GDALSetDefaultHistogram( GDALRasterBandH hBand, double dfMin, double dfMax, - int nBuckets, int *panHistogram ) CPL_WARN_DEPRECATED("Use GDALSetDefaultHistogramEx() instead"); + int nBuckets, int *panHistogram ) +/*! @cond Doxygen_Suppress */ + CPL_WARN_DEPRECATED("Use GDALSetDefaultHistogramEx() instead") +/*! @endcond */ + ; CPLErr CPL_DLL CPL_STDCALL GDALSetDefaultHistogramEx( GDALRasterBandH hBand, double dfMin, double dfMax, int nBuckets, GUIntBig *panHistogram ); diff --git a/gdal/gcore/gdal_priv.h b/gdal/gcore/gdal_priv.h index 6790daf7110..f30269be6f7 100644 --- a/gdal/gcore/gdal_priv.h +++ b/gdal/gcore/gdal_priv.h @@ -604,7 +604,9 @@ class CPL_DLL GDALDataset : public GDALMajorObject CPLErr BuildOverviews( const char *, int, int *, int, int *, GDALProgressFunc, void * ); +#ifndef DOXYGEN_XML void ReportError(CPLErr eErrClass, CPLErrorNum err_no, const char *fmt, ...) CPL_PRINT_FUNC_FORMAT (4, 5); +#endif char ** GetMetadata(const char * pszDomain = "") override; @@ -612,8 +614,6 @@ class CPL_DLL GDALDataset : public GDALMajorObject #ifdef DOXYGEN_SKIP CPLErr SetMetadata( char ** papszMetadata, const char * pszDomain ) override; - const char *GetMetadataItem( const char * pszName, - const char * pszDomain ) override; CPLErr SetMetadataItem( const char * pszName, const char * pszValue, const char * pszDomain ) override; @@ -1252,11 +1252,8 @@ class CPL_DLL GDALRasterBand : public GDALMajorObject // Only defined when Doxygen enabled #ifdef DOXYGEN_SKIP - char **GetMetadata( const char * pszDomain = "" ) override; CPLErr SetMetadata( char ** papszMetadata, const char * pszDomain ) override; - const char *GetMetadataItem( const char * pszName, - const char * pszDomain ) override; CPLErr SetMetadataItem( const char * pszName, const char * pszValue, const char * pszDomain ) override; diff --git a/gdal/ogr/ogr_geometry.h b/gdal/ogr/ogr_geometry.h index d7de8f07555..ef220d19747 100644 --- a/gdal/ogr/ogr_geometry.h +++ b/gdal/ogr/ogr_geometry.h @@ -421,13 +421,18 @@ class CPL_DLL OGRGeometry OGRwkbVariant=wkbVariantOldOgc ) const = 0; virtual OGRErr importFromWkt( const char ** ppszInput ) = 0; +#ifndef DOXYGEN_XML /** Deprecated. * @deprecated in GDAL 2.3 */ - OGRErr importFromWkt( char ** ppszInput ) CPL_WARN_DEPRECATED("Use importFromWkt(const char**) instead") + OGRErr importFromWkt( char ** ppszInput ) +/*! @cond Doxygen_Suppress */ + CPL_WARN_DEPRECATED("Use importFromWkt(const char**) instead") +/*! @endcond */ { return importFromWkt( const_cast(ppszInput) ); } +#endif OGRErr exportToWkt( char ** ppszDstText, OGRwkbVariant=wkbVariantOldOgc ) const; @@ -881,9 +886,16 @@ class CPL_DLL OGRPoint : public OGRGeometry OGRErr exportToWkb( OGRwkbByteOrder, unsigned char *, OGRwkbVariant=wkbVariantOldOgc ) const override; + +#ifndef DOXYGEN_XML using OGRGeometry::importFromWkt; /** deprecated */ +#endif + OGRErr importFromWkt( const char ** ) override; + +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a point to WKT /// \param opts Output options. @@ -1187,9 +1199,16 @@ class CPL_DLL OGRSimpleCurve: public OGRCurve virtual OGRErr exportToWkb( OGRwkbByteOrder, unsigned char *, OGRwkbVariant=wkbVariantOldOgc ) const override; + +#ifndef DOXYGEN_XML using OGRGeometry::importFromWkt; /** deprecated */ +#endif + OGRErr importFromWkt( const char ** ) override; + +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a simple curve to WKT /// \param opts Output options. @@ -1481,9 +1500,16 @@ class CPL_DLL OGRCircularString : public OGRSimpleCurve virtual OGRErr exportToWkb( OGRwkbByteOrder, unsigned char *, OGRwkbVariant=wkbVariantOldOgc ) const override; + +#ifndef DOXYGEN_XML using OGRGeometry::importFromWkt; /** deprecated */ +#endif + OGRErr importFromWkt( const char ** ) override; + +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a circular string to WKT /// \param opts Output options. @@ -1701,9 +1727,16 @@ class CPL_DLL OGRCompoundCurve : public OGRCurve virtual OGRErr exportToWkb( OGRwkbByteOrder, unsigned char *, OGRwkbVariant=wkbVariantOldOgc ) const override; + +#ifndef DOXYGEN_XML using OGRGeometry::importFromWkt; /** deprecated */ +#endif + OGRErr importFromWkt( const char ** ) override; + +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a compound curve to WKT /// \param opts Output options. @@ -1904,9 +1937,16 @@ class CPL_DLL OGRCurvePolygon : public OGRSurface virtual OGRErr exportToWkb( OGRwkbByteOrder, unsigned char *, OGRwkbVariant=wkbVariantOldOgc ) const override; + +#ifndef DOXYGEN_XML using OGRGeometry::importFromWkt; /** deprecated */ +#endif + OGRErr importFromWkt( const char ** ) override; + +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a curve polygon to WKT /// \param opts Output options. @@ -2048,10 +2088,16 @@ class CPL_DLL OGRPolygon : public OGRCurvePolygon virtual OGRErr exportToWkb( OGRwkbByteOrder, unsigned char *, OGRwkbVariant=wkbVariantOldOgc ) const override; + +#ifndef DOXYGEN_XML using OGRGeometry::importFromWkt; /** deprecated */ +#endif + OGRErr importFromWkt( const char ** ) override; +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a polygon to WKT /// \param opts Output options. @@ -2238,10 +2284,16 @@ class CPL_DLL OGRGeometryCollection : public OGRGeometry virtual OGRErr exportToWkb( OGRwkbByteOrder, unsigned char *, OGRwkbVariant=wkbVariantOldOgc ) const override; + +#ifndef DOXYGEN_XML using OGRGeometry::importFromWkt; /** deprecated */ +#endif + OGRErr importFromWkt( const char ** ) override; +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a geometry collection to WKT /// \param opts Output options. @@ -2341,10 +2393,16 @@ class CPL_DLL OGRMultiSurface : public OGRGeometryCollection // Non standard (OGRGeometry). virtual const char *getGeometryName() const override; virtual OGRwkbGeometryType getGeometryType() const override; + +#ifndef DOXYGEN_XML using OGRGeometry::importFromWkt; /** deprecated */ +#endif + OGRErr importFromWkt( const char ** ) override; +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a geometry collection to WKT /// \param opts Output options. @@ -2439,7 +2497,10 @@ class CPL_DLL OGRMultiPolygon : public OGRMultiSurface // Non-standard (OGRGeometry). virtual const char *getGeometryName() const override; virtual OGRwkbGeometryType getGeometryType() const override; + +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a multipolygon to WKT /// \param opts Output options. @@ -2538,9 +2599,16 @@ class CPL_DLL OGRPolyhedralSurface : public OGRSurface virtual OGRErr exportToWkb( OGRwkbByteOrder, unsigned char *, OGRwkbVariant=wkbVariantOldOgc ) const override; + +#ifndef DOXYGEN_XML using OGRGeometry::importFromWkt; /** deprecated */ +#endif + OGRErr importFromWkt( const char ** ) override; + +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a polyhedral surface to WKT /// \param opts Output options. @@ -2718,9 +2786,16 @@ class CPL_DLL OGRMultiPoint : public OGRGeometryCollection // Non-standard (OGRGeometry). virtual const char *getGeometryName() const override; virtual OGRwkbGeometryType getGeometryType() const override; + +#ifndef DOXYGEN_XML using OGRGeometry::importFromWkt; /** deprecated */ +#endif + OGRErr importFromWkt( const char ** ) override; + +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a multipoint to WKT /// \param opts Output options. @@ -2803,9 +2878,16 @@ class CPL_DLL OGRMultiCurve : public OGRGeometryCollection // Non standard (OGRGeometry). virtual const char *getGeometryName() const override; virtual OGRwkbGeometryType getGeometryType() const override; + +#ifndef DOXYGEN_XML using OGRGeometry::importFromWkt; /** deprecated */ +#endif + OGRErr importFromWkt( const char ** ) override; + +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a multicurve to WKT /// \param opts Output options. @@ -2884,7 +2966,10 @@ class CPL_DLL OGRMultiLineString : public OGRMultiCurve // Non standard (OGRGeometry). virtual const char *getGeometryName() const override; virtual OGRwkbGeometryType getGeometryType() const override; + +#ifndef DOXYGEN_XML using OGRGeometry::exportToWkt; +#endif /// Export a multilinestring to WKT /// \param opts Output options. diff --git a/gdal/ogr/ogr_spatialref.h b/gdal/ogr/ogr_spatialref.h index 23237a62091..a97af16ece7 100644 --- a/gdal/ogr/ogr_spatialref.h +++ b/gdal/ogr/ogr_spatialref.h @@ -293,7 +293,11 @@ class CPL_DLL OGRSpatialReference const char *pszUnitAuthority = nullptr, const char *pszUnitCode = nullptr); - double GetLinearUnits( char ** ) const CPL_WARN_DEPRECATED("Use GetLinearUnits(const char**) instead"); + double GetLinearUnits( char ** ) const +/*! @cond Doxygen_Suppress */ + CPL_WARN_DEPRECATED("Use GetLinearUnits(const char**) instead") +/*! @endcond */ + ; double GetLinearUnits( const char ** = nullptr ) const; /*! @cond Doxygen_Suppress */ double GetLinearUnits( std::nullptr_t ) const @@ -302,7 +306,10 @@ class CPL_DLL OGRSpatialReference double GetTargetLinearUnits( const char *pszTargetKey, char ** ppszRetName ) const - CPL_WARN_DEPRECATED("Use GetTargetLinearUnits(const char*, const char**)"); +/*! @cond Doxygen_Suppress */ + CPL_WARN_DEPRECATED("Use GetTargetLinearUnits(const char*, const char**)") +/*! @endcond */ + ; double GetTargetLinearUnits( const char *pszTargetKey, const char ** ppszRetName = nullptr ) const; /*! @cond Doxygen_Suppress */ @@ -311,14 +318,22 @@ class CPL_DLL OGRSpatialReference /*! @endcond */ OGRErr SetAngularUnits( const char *pszName, double dfInRadians ); - double GetAngularUnits( char ** ) const CPL_WARN_DEPRECATED("Use GetAngularUnits(const char**) instead"); + double GetAngularUnits( char ** ) const +/*! @cond Doxygen_Suppress */ + CPL_WARN_DEPRECATED("Use GetAngularUnits(const char**) instead") +/*! @endcond */ + ; double GetAngularUnits( const char ** = nullptr ) const; /*! @cond Doxygen_Suppress */ double GetAngularUnits( std::nullptr_t ) const { return GetAngularUnits( static_cast(nullptr) ); } /*! @endcond */ - double GetPrimeMeridian( char ** ) const CPL_WARN_DEPRECATED("Use GetPrimeMeridian(const char**) instead"); + double GetPrimeMeridian( char ** ) const +/*! @cond Doxygen_Suppress */ + CPL_WARN_DEPRECATED("Use GetPrimeMeridian(const char**) instead") +/*! @endcond */ + ; double GetPrimeMeridian( const char ** = nullptr ) const; /*! @cond Doxygen_Suppress */ double GetPrimeMeridian( std::nullptr_t ) const diff --git a/gdal/port/cpl_conv.h b/gdal/port/cpl_conv.h index a3ee4e7318d..e6f03396e32 100644 --- a/gdal/port/cpl_conv.h +++ b/gdal/port/cpl_conv.h @@ -178,7 +178,7 @@ const char CPL_DLL *CPLLaunderForFilename(const char* pszName, /* -------------------------------------------------------------------- */ /** Callback for CPLPushFileFinder */ -typedef const char *(*CPLFileFinder)(const char *, const char *); +typedef char const *(*CPLFileFinder)(const char *, const char *); const char CPL_DLL *CPLFindFile(const char *pszClass, const char *pszBasename);