[clang][NFC] Add documentation for CastExpr::path().

[martinboehme]

This didn't have any documentation, so I had to do some experimenting in godbolt when I used this in #84138, and my reviewer later also had some questions about this, so I figured it would be worth adding documentation.

[llvmbot]

@llvm/pr-subscribers-clang

Author: None (martinboehme)

Changes

This didn't have any documentation, so I had to do some experimenting in
godbolt when I used this in #84138,
and my reviewer later also had some
questions
about this, so I figured it would be worth adding documentation.

---

Full diff: https://github.com/llvm/llvm-project/pull/85623.diff

1 Files Affected:

• (modified) clang/include/clang/AST/Expr.h (+9)

diff --git a/clang/include/clang/AST/Expr.h b/clang/include/clang/AST/Expr.h
index 446bec4081e869..8c4db4828477d0 100644
--- a/clang/include/clang/AST/Expr.h
+++ b/clang/include/clang/AST/Expr.h
@@ -3552,6 +3552,15 @@ class CastExpr : public Expr {
   /// function that it invokes.
   NamedDecl *getConversionFunction() const;
 
+  /// Path through the class hierarchy taken by a `DerivedToBase` or
+  /// `UncheckedDerivedToBase` cast. For each derived-to-base edge in the path,
+  /// the path contains a `CXXBaseSpecifier` for the base class of that edge;
+  /// the entries are ordered from derived class to base class.
+  ///
+  /// For example, given classes `Base`, `Intermediate : public Base` and
+  /// `Derived : public Intermediate`, the path for a cast from `Derived *` to
+  /// `Base *` contains two entries: One for `Intermediate`, and one for `Base`,
+  /// in that order.
   typedef CXXBaseSpecifier **path_iterator;
   typedef const CXXBaseSpecifier *const *path_const_iterator;
   bool path_empty() const { return path_size() == 0; }

[ymand]

thanks!

[rjmccall]

You can see in CastConsistency the set of cast kinds that require a base path; it's more than just these two.

[martinboehme]

Thanks for pointing this out! I've fixed this -- WDYT?

[tbaederr]

Does this actually show up at the right place? Or is it now the documentation for path_empty()? Or even path_iterator?

[martinboehme]

Does this actually show up at the right place? Or is it now the documentation for path_empty()? Or even path_iterator?

Hm, good question. This seemed the most logical place to put the documentation in the source code, but of course, once it gets processed by Doxygen, it will probably get attached to something we don't want.

I've moved the documentation down, right above the declaration of path(). WDYT?

[tbaederr]

I've moved the documentation down, right above the declaration of path(). WDYT?

I think that should work.