resource_retriever generated error in default Doxyfile in PROJECT_BRIEF

[rkent]

Error in build farm is:

03:58:38 [rosdoc2] [INFO] Running Doxygen: 'doxygen Doxyfile.rosdoc2' in '/tmp/ws/docs_build/resource_retriever/resource_retriever-public-cc-api'
03:58:38 warning: Invalid value for 'PROJECT_BRIEF' tag at line 8, file Doxyfile.rosdoc2_default: Value '"This package retrieves data from url-format files such as http://,' is not properly quoted

The offending portion of the Doxyfile is:

PROJECT_NUMBER         = 3.4.1
PROJECT_BRIEF          = "This package retrieves data from url-format files such as http://,
   ftp://, package:// file://, etc., and loads the data into memory.
   The package:// url for ros packages is translated into a local
   file:// url.  The resourse retriever was initially designed to load
   mesh files into memory, but it can be used for any type of
   data. The resource retriever is based on the the libcurl library."

INPUT                  = /home/kent/github/ros/resource_retriever/resource_retriever/include

The long PROJECT_BRIEF comes from package.xml:

  <description>
   This package retrieves data from url-format files such as http://,
   ftp://, package:// file://, etc., and loads the data into memory.
   The package:// url for ros packages is translated into a local
   file:// url.  The resourse retriever was initially designed to load
   mesh files into memory, but it can be used for any type of
   data. The resource retriever is based on the the libcurl library.
  </description>

[rkent]

Doxygen documentation gives:

PROJECT_BRIEF

Using the PROJECT_BRIEF tag one can provide an optional one line description for a project that appears at the top of each page and should give viewer a quick idea about the purpose of the project. Keep the description short.

while ROS documentation states:

\<description>

The description of the package. It can consist of multiple lines and may contain XHTML. But depending on where the description is used XML tags and multiple whitespaces might be stripped.

So we really should not be using the multi-line description as PROJECT_BRIEF.

This does not really affect what we are showing. I think the short answer would be to make PROJECT_BRIEF be "ROS2 package {package.name}" and if a package is really showing somehow the actual Doxygen output, let them customize it. I just want to get rid of the nuisance errors.

[rkent]

We actually do make the Doxygen output available (though hidden). You can see the result here:

http://docs.ros.org/en/rolling/p/resource_retriever/generated/doxygen/html/

Namely, Doxygen truncated the PROJECT_BRIEF to just the first line, so it shows:

This package retrieves data from url-format files such as http://,

So this is just a nuisance warning. In the event that some package wants to promote their Doxygen output, the description (even if truncated) is a better look than my previous recommendation "ROS2 package {package.name}" so we should leave the result alone. Maybe we could truncate ourselves to eliminate the nuisance warning.