doxdrift: four declaration shapes parsed as the argument list (69 findings on PCL, 4 real of 28 checked)

[darkdi]

Run: doxdrift.py fingerprint 77d0a1e9, 2026-08-06, over PointCloudLibrary/pcl at master (sparse checkout of */include). Reported 69 hard, 0 soft across 1107 headers and 4215 \param blocks. Counters say function pointers read: 0.

I read 28 of the 69 by hand. Four of them are real; the rest fail on four shapes of declaration, each of which the tool parses as something other than the argument list. All four reproduce on this repo.

1. Member-function-pointer parameter — the T::* form

io/include/pcl/io/openni_camera/openni_device.h:293 (also :321, :348)

template<typename T> CallbackHandle
registerImageCallback (void (T::*callback)(Image::Ptr, void* cookie), T& instance, void* cookie = nullptr) noexcept;

Tool says: documented callback, declaration has cookie, instance, cookie. The name is callback, and it sits in the first pair of parentheses exactly like the plain function-pointer case the tool already knows about — but function pointers read: 0, so the T::* spelling is not matched by that path. Cost here: 3 false findings.

2. Constructor with a member-initializer list — declaration read as empty

io/include/pcl/compression/octree_pointcloud_compression.h:86

OctreePointCloudCompression (compression_Profiles_e compressionProfile_arg = MED_RES_ONLINE_COMPRESSION_WITH_COLOR,
                       bool showStatistics_arg = false,
                       ...
                       const unsigned char colorBitResolution_arg = 6) :
  OctreePointCloud<PointT, LeafT, BranchT, OctreeT> (octreeResolution_arg),
  output_ (PointCloudPtr ()),
  ...

Tool says in the declaration: (empty) for all eight documented names. All eight are present in the signature. Cost: 8 false findings from one docblock — the largest single cluster in the run.

3. Return type or template prefix read as the argument list

io/include/pcl/io/ply_io.h:280 and :287

template <typename ScalarType> std::function<void (ScalarType)>
scalarPropertyDefinitionCallback (const std::string& element_name, const std::string& property_name);

Tool says: documented element_name, declaration has ScalarType. It took the template parameter list (or the parenthesis inside the return type) as the arguments. Same shape at registration/include/pcl/registration/registration.h:96 (declaration reported as PointSource, Indices, PointTarget, Indices) and features/include/pcl/features/don.h:125 (PointCloudOut).

io/include/pcl/io/ply_io.h:270 is the same породы with the opposite symptom — the return type std::tuple<std::function<void ()>, std::function<void ()> > gives (empty), while elementDefinitionCallback (const std::string& element_name, std::size_t count) documents both names correctly.

4. Unnamed parameter — arguably out of scope, but it reports as a mismatch

keypoints/include/pcl/keypoints/harris_2d.h:115 (also harris_3d.h:122, harris_6d.h:102)

/** \param[in] nonmax default is false */
void setNonMaxSupression (bool = false);

The parameter has no name in the declaration, so the tool reports in the declaration: bool. There is a real problem here, but the fix is to name the parameter, which is a code change — not something a docstring pass should send. Might be worth a separate soft class rather than a hard finding.

What survived

Four real ones, for the record: io/include/pcl/io/openni2_grabber.h:234 (rgb_focal_ulength_y → rgb_focal_length_y), geometry/include/pcl/geometry/mesh_elements.h:166 (inner_half_edge_idx → idx_inner_half_edge), registration/include/pcl/registration/correspondence_estimation.h:307 (docblock copied from the non-reciprocal setter above it), recognition/include/pcl/recognition/crh_alignment.h:65 (transformation is prose, the argument is transform).

Note that shapes 1–3 are all "the parentheses the tool measured are not the argument list". PCL puts the return type on its own line above the name, which seems to be what makes them so frequent here — 24 of the 28 I checked.

[karpovantonme]

All five shapes are fixed, and the fifth turned out not to be a parse bug at all. Numbers below are from the same tree you ran.

What each one was

Member function pointer. DECLARATOR demanded [*&] before the optional Class::, so void (T::*cb)(...) never matched it. The star belongs after the qualification.

Return type carrying a call signature. Both std::function<void (X)> f(y) and the empty-bracket variant come down to one rule: nothing inside <...> can be an argument list, because that is a template argument. The parser now counts bracket depth before accepting a parenthesis.

Unnamed parameter. You were right that this should not be hard. It is soft now, with its own line in the coverage block. The docstring is not wrong; the declaration has nowhere to attach it, and naming the parameter is a code change.

Constructor with an initializer list -- this one was not about parsing arguments. sig_params handled that declaration correctly all along. The problem was upstream: a declaration is matched up to { or ; with a 900-character cut, and the argument list plus the initializers runs past it, so the match slid forward and the docblock was compared against the next declaration in the file -- the destructor below. Hence eight findings from one comment, and hence (empty): the destructor really does take nothing. A declaration now also ends at the : that opens the list.

Two more that were hiding behind it

Once the constructor stopped shadowing them:

• void compute (PointCloudOut &) -- a bare user type. The keyword list did not cover it, since PointCloudOut is not bool.
• using S = void(const pcl::PointCloud<PointSource>&, ...) -- the last word of a decorated type is a template argument, and it was reported as the parameter PointSource.

Both collapse into one rule: anything ending in &, * or > has no name to take.

I first tried skipping using and typedef wholesale, and two tests caught it immediately -- that would have killed the typedef void (*MouseCallback)(int event, int x, int y) case, where the names are real and there were 111 findings on opencv. The predicate is "nothing to compare against", not "type alias".

Your counter observation

function pointers read: 0 was true and useless: only the shape where the pointer is the function NAME was counted. A pointer as an ARGUMENT goes down a different path. Split into two lines, and PCL shows 33 of the second and none of the first.

PCL, same tree

your run:  69 hard,  1107 headers
now:       59 hard, 8 soft, 1389 headers

The header count differs because the tool globbed *.hpp only until this morning -- .h trees reported a clean zero and looked checked. That was found the same day on protobuf (6 headers read of 611) and abseil (0 of 385).

All eight sites you called false are clean. All four you confirmed as real are still reported:

openni_device.h                  clean      openni2_grabber.h            reported
octree_pointcloud_compression.h  clean      mesh_elements.h              reported
ply_io.h                         clean      correspondence_estimation.h  reported
registration.h                   clean      crh_alignment.h              reported
don.h, harris_2d/3d/6d.h         soft

Regression: 49 tests, Boost gil/graph/math stay at zero, t8code/OpenMD/PeriDEM keep their five each, and votca's single false one is gone -- that was the same constructor shape, found here independently the same day.

Cases 96 to 102 are in FALSE-POSITIVES.md, which is at 106 now.

Thanks for reading 28 of them by hand and writing down the mechanism rather than the symptom. The fifth would not have been findable from a symptom -- it looks like an argument-parsing bug from the outside and is nothing of the kind.

About rstdrift

Send it as a pull request rather than pasting it -- there is no equivalent here, docdrift only speaks numpydoc. Same bar as the rest of the kit: a docstring naming the species, coverage counters in the report, and at least one test pinned to a live case. If you hit false positives on the way, a row in FALSE-POSITIVES.md with the cost is worth more than the fix itself.