define_property(): Make BRIEF_DOCS and FULL_DOCS optional

Issue: #20698

Help/command/define_property.rst

@@ -8,8 +8,8 @@ Define and document custom properties.
   define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
                    TEST | VARIABLE | CACHED_VARIABLE>
                    PROPERTY <name> [INHERITED]
-                   BRIEF_DOCS <brief-doc> [docs...]
-                   FULL_DOCS <full-doc> [docs...])
+                   [BRIEF_DOCS <brief-doc> [docs...]]
+                   [FULL_DOCS <full-doc> [docs...]])
 
 Defines one property in a scope for use with the :command:`set_property` and
 :command:`get_property` commands.  This is primarily useful to associate

Help/release/dev/define-property-optional-args.rst

@@ -0,0 +1,5 @@
+define-property-optional-args
+-----------------------------
+
+* The :command:`define_property` ``BRIEF_DOCS`` and ``FULL_DOCS`` arguments are
+  now optional.

Source/cmDefinePropertyCommand.cxx

@@ -2,13 +2,13 @@
    file Copyright.txt or https://cmake.org/licensing for details.  */
 #include "cmDefinePropertyCommand.h"
 
-#include <cm/string_view>
 #include <cmext/string_view>
 
 #include "cmArgumentParser.h"
 #include "cmExecutionStatus.h"
 #include "cmMakefile.h"
 #include "cmProperty.h"
+#include "cmRange.h"
 #include "cmState.h"
 #include "cmStringAlgorithms.h"
 
@@ -71,16 +71,6 @@ bool cmDefinePropertyCommand(std::vector<std::string> const& args,
     return false;
   }
 
-  // Make sure documentation was given.
-  if (BriefDocs.empty()) {
-    status.SetError("not given a BRIEF_DOCS <brief-doc> argument.");
-    return false;
-  }
-  if (FullDocs.empty()) {
-    status.SetError("not given a FULL_DOCS <full-doc> argument.");
-    return false;
-  }
-
   // Actually define the property.
   status.GetMakefile().GetState()->DefineProperty(
     PropertyName, scope, cmJoin(BriefDocs, ""), cmJoin(FullDocs, ""),

Source/cmGetPropertyCommand.cxx

@@ -184,7 +184,8 @@ bool cmGetPropertyCommand(std::vector<std::string> const& args,
           status.GetMakefile().GetState()->GetPropertyDefinition(propertyName,
                                                                  scope)) {
       output = def->GetShortDescription();
-    } else {
+    }
+    if (output.empty()) {
       output = "NOTFOUND";
     }
     status.GetMakefile().AddDefinition(variable, output);
@@ -195,7 +196,8 @@ bool cmGetPropertyCommand(std::vector<std::string> const& args,
           status.GetMakefile().GetState()->GetPropertyDefinition(propertyName,
                                                                  scope)) {
       output = def->GetFullDescription();
-    } else {
+    }
+    if (output.empty()) {
       output = "NOTFOUND";
     }
     status.GetMakefile().AddDefinition(variable, output);

Tests/RunCMake/CMakeLists.txt

@@ -418,6 +418,7 @@ add_RunCMake_test(ctest_update)
 add_RunCMake_test(ctest_upload)
 add_RunCMake_test(ctest_environment)
 add_RunCMake_test(ctest_fixtures)
+add_RunCMake_test(define_property)
 add_RunCMake_test(file -DCYGWIN=${CYGWIN} -DMSYS=${MSYS})
 add_RunCMake_test(file-CHMOD -DMSYS=${MSYS})
 add_RunCMake_test(file-RPATH -DCMAKE_SYSTEM_NAME=${CMAKE_SYSTEM_NAME})

Tests/RunCMake/define_property/CMakeLists.txt

@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 3.22)
+project(${RunCMake_TEST} NONE)
+include(${RunCMake_TEST}.cmake)

Tests/RunCMake/define_property/RunCMakeTest.cmake

@@ -0,0 +1,3 @@
+include(RunCMake)
+
+run_cmake(define_property)

Tests/RunCMake/define_property/define_property.cmake

@@ -0,0 +1,26 @@
+function(assert_prop_scope_eq prop scope value)
+  get_property(actual_value TARGET NONE PROPERTY ${prop} ${scope})
+  if(NOT actual_value STREQUAL value)
+    message(SEND_ERROR "Expected value of ${prop}'s ${scope}:\n  ${value}\nActual value:\n  ${actual_value}")
+  endif()
+endfunction()
+
+define_property(TARGET PROPERTY PROP1)
+define_property(TARGET PROPERTY PROP2
+  BRIEF_DOCS "Brief")
+define_property(TARGET PROPERTY PROP3
+  FULL_DOCS "Full")
+define_property(TARGET PROPERTY PROP4
+  BRIEF_DOCS "Brief"
+  FULL_DOCS "Full")
+
+assert_prop_scope_eq(PROP0 BRIEF_DOCS "NOTFOUND")
+assert_prop_scope_eq(PROP0 FULL_DOCS "NOTFOUND")
+assert_prop_scope_eq(PROP1 BRIEF_DOCS "NOTFOUND")
+assert_prop_scope_eq(PROP1 FULL_DOCS "NOTFOUND")
+assert_prop_scope_eq(PROP2 BRIEF_DOCS "Brief")
+assert_prop_scope_eq(PROP2 FULL_DOCS "NOTFOUND")
+assert_prop_scope_eq(PROP3 BRIEF_DOCS "NOTFOUND")
+assert_prop_scope_eq(PROP3 FULL_DOCS "Full")
+assert_prop_scope_eq(PROP4 BRIEF_DOCS "Brief")
+assert_prop_scope_eq(PROP4 FULL_DOCS "Full")