[C++][Doc] Fix warnings generated by sphinx when incorporating doxygen docs

[asfimport]

Sphinx interprets the doxygen output to build the final documentation.  This process generates some warnings.

 

This warning is generated when running doxygen:

warning: Tag 'COLS_IN_ALPHA_INDEX' at line 1118 of file 'Doxyfile' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"

There are many warnings contributed to compute.rst that look like this (it is unclear where this static constexpr static is coming from as it is not present in the repo or doxygen that I can find):

/home/pace/dev/arrow/docs/source/cpp/api/compute.rst:51: WARNING: Invalid C++ declaration: Expected identifier in nested name, got keyword: static [error at 23]
  static constexpr static char const kTypeName []  = "ScalarAggregateOptions"

There is a duplicate definition warning (I think this one is because the doc comment is present on both the definition and the override)

/home/pace/dev/arrow/docs/source/cpp/api/dataset.rst:69: WARNING: Duplicate declaration, Result< std::shared_ptr< FileFragment > > MakeFragment (FileSource source, compute::Expression partition_expression, std::shared_ptr< Schema > physical_schema)

Finally, there is a specific issue with the GetRecordBatchGenerator function

/home/pace/dev/arrow/docs/source/cpp/api/formats.rst:80: WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters-and-qualifiers
  Main error:
    Invalid C++ declaration: Expecting "(" in parameters-and-qualifiers. [error at 23]
      virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
      -----------------------^
  Potential other error:
    Error in parsing template argument list.
    If type argument:
      Main error:
        Invalid C++ declaration: Expected "...>", ">" or "," in template argument list. [error at 38]
          virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
          --------------------------------------^
      Potential other error:
        Main error:
          Invalid C++ declaration: Expected identifier in nested name. [error at 38]
            virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
            --------------------------------------^
        Potential other error:
          Error in parsing template argument list.
          If type argument:
            Invalid C++ declaration: Expected "...>", ">" or "," in template argument list. [error at 96]
              virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
              ------------------------------------------------------------------------------------------------^
          If non-type argument:
            Invalid C++ declaration: Expected "...>", ">" or "," in template argument list. [error at 96]
              virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
              ------------------------------------------------------------------------------------------------^
    If non-type argument:
      Invalid C++ declaration: Expected "...>", ">" or "," in template argument list. [error at 96]
        virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
        ------------------------------------------------------------------------------------------------^
If the function has a return type:
  Error in declarator or parameters-and-qualifiers
  If pointer to member declarator:
    Main error:
      Invalid C++ declaration: Expected identifier in nested name. [error at 23]
        virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
        -----------------------^
    Potential other error:
      Error in parsing template argument list.
      If type argument:
        Main error:
          Invalid C++ declaration: Expected "...>", ">" or "," in template argument list. [error at 38]
            virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
            --------------------------------------^
        Potential other error:
          Main error:
            Invalid C++ declaration: Expected identifier in nested name. [error at 38]
              virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
              --------------------------------------^
          Potential other error:
            Error in parsing template argument list.
            If type argument:
              Invalid C++ declaration: Expected "...>", ">" or "," in template argument list. [error at 96]
                virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
                ------------------------------------------------------------------------------------------------^
            If non-type argument:
              Invalid C++ declaration: Expected "...>", ">" or "," in template argument list. [error at 96]
                virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
                ------------------------------------------------------------------------------------------------^
      If non-type argument:
        Invalid C++ declaration: Expected "...>", ">" or "," in template argument list. [error at 96]
          virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
          ------------------------------------------------------------------------------------------------^
  If declarator-id:
    Invalid C++ declaration: Expected identifier in nested name. [error at 23]
      virtual ::arrow::Result< std::function<::arrow::Future< std::shared_ptr<::arrow::RecordBatch > >)> > GetRecordBatchGenerator (std::shared_ptr< FileReader > reader, const std::vector< int > row_group_indices, const std::vector< int > column_indices, ::arrow::internal::Executor *cpu_executor=NULLPTR)=0
      -----------------------^

Reporter: Weston Pace / @westonpace

_{Note: This issue was originally created as ARROW-13316. Please see the migration documentation for further details.}

[asfimport]

Joris Van den Bossche / @jorisvandenbossche:
I was chatting about this with @bkietz, and tried out his suggestion to disable doxygen for all the kTypeName declarations, like:

  /// \cond false
  constexpr static char const kTypeName[] = "VarianceOptions";
  /// \endcond

This seems to fix the warning, and simply removed the kTypeName value from the documentation (which I assume is fine).

[asfimport]

Apache Arrow JIRA Bot:
This issue was last updated over 90 days ago, which may be an indication it is no longer being actively worked. To better reflect the current state, the issue is being unassigned per project policy. Please feel free to re-take assignment of the issue if it is being actively worked, or if you plan to start that work soon.

[github-actions]

This issue has been marked as stale because it has had no activity in the past 365 days. Please remove the stale label or comment below, or this issue will be closed in 14 days. If this improvement is still desired but has no current owner, please add the 'Status: needs champion' label.