Doc of GDALWarpApp()/GDALTranslate()/GDALBuildVRT(): better document …

…ownership

apps/gdal_translate_lib.cpp

@@ -677,7 +677,12 @@ static double AdjustNoDataValue(double dfInputNoDataValue,
  * @param pbUsageError pointer to a integer output variable to store if any
  * usage error has occurred or NULL.
  * @return the output dataset (new dataset that must be closed using
- * GDALClose()) or NULL in case of error.
+ * GDALClose()) or NULL in case of error. If the output
+ * format is a VRT dataset, then the returned VRT dataset has a reference to
+ * hSrcDataset. Hence hSrcDataset should be closed after the returned dataset
+ * if using GDALClose().
+ * A safer alternative is to use GDALReleaseDataset() instead of using
+ * GDALClose(), in which case you can close datasets in any order.
  *
  * @since GDAL 2.1
  */

apps/gdalbuildvrt_lib.cpp

@@ -1809,15 +1809,22 @@ GDALBuildVRTOptionsClone(const GDALBuildVRTOptions *psOptionsIn)
  * @param pszDest the destination dataset path.
  * @param nSrcCount the number of input datasets.
  * @param pahSrcDS the list of input datasets (or NULL, exclusive with
- * papszSrcDSNames)
+ * papszSrcDSNames). For practical purposes, the type
+ * of this argument should be considered as "const GDALDatasetH* const*", that
+ * is neither the array nor its values are mutated by this function.
  * @param papszSrcDSNames the list of input dataset names (or NULL, exclusive
  * with pahSrcDS)
  * @param psOptionsIn the options struct returned by GDALBuildVRTOptionsNew() or
  * NULL.
  * @param pbUsageError pointer to a integer output variable to store if any
  * usage error has occurred.
  * @return the output dataset (new dataset that must be closed using
- * GDALClose()) or NULL in case of error.
+ * GDALClose()) or NULL in case of error. If using pahSrcDS, the returned VRT
+ * dataset has a reference to each pahSrcDS[] element. Hence pahSrcDS[] elements
+ * should be closed after the returned dataset if using GDALClose().
+ * A safer alternative is to use GDALReleaseDataset() instead of using
+ * GDALClose(), in which case you can close datasets in any order.
+
  *
  * @since GDAL 2.1
  */

apps/gdalwarp_lib.cpp

@@ -1365,13 +1365,20 @@ static GDALDatasetH GDALWarpIndirect(const char *pszDest, GDALDriverH hDriver,
  * @param pszDest the destination dataset path or NULL.
  * @param hDstDS the destination dataset or NULL.
  * @param nSrcCount the number of input datasets.
- * @param pahSrcDS the list of input datasets.
+ * @param pahSrcDS the list of input datasets. For practical purposes, the type
+ * of this argument should be considered as "const GDALDatasetH* const*", that
+ * is neither the array nor its values are mutated by this function.
  * @param psOptionsIn the options struct returned by GDALWarpAppOptionsNew() or
  * NULL.
  * @param pbUsageError pointer to a integer output variable to store if any
  * usage error has occurred, or NULL.
  * @return the output dataset (new dataset that must be closed using
- * GDALClose(), or hDstDS if not NULL) or NULL in case of error.
+ * GDALClose(), or hDstDS if not NULL) or NULL in case of error. If the output
+ * format is a VRT dataset, then the returned VRT dataset has a reference to
+ * pahSrcDS[0]. Hence pahSrcDS[0] should be closed after the returned dataset
+ * if using GDALClose().
+ * A safer alternative is to use GDALReleaseDataset() instead of using
+ * GDALClose(), in which case you can close datasets in any order.
  *
  * @since GDAL 2.1
  */