Correct Doxygen syntax for inline code

[aaronpuchert]

Summary

There is no syntax like {@code ...} in Doxygen, @code is a block command
that ends with @endcode, and generally these are not enclosed in braces.
The correct syntax for inline code snippets is @c <code>.

[aaron.ballman]

LGTM! I wonder if this is something our -Wdocumentation should warn about?

[aaronpuchert]

In D98665#2628851, @aaron.ballman wrote:

LGTM! I wonder if this is something our -Wdocumentation should warn about?

Interestingly we warn about the opposite problem:

/// @endcode
int x;

produces "warning: '@endcode' command does not terminate a verbatim text block [-Wdocumentation]".

Maybe we're deliberately not doing this because it would be too annoying, not sure. Maybe @gribozavr2 knows that.

clang/include/clang/Analysis/AnyCall.h

AnyCall(const FunctionDecl *D) : E(nullptr), D(D) {
     } else if (isa <CXXDestructorDecl>(D)) {
       K = Destructor;
     } else {
       K = Function;
     }
 
   }
 
-  /// If {@code E} is a generic call (to ObjC method /function/block/etc),
-  /// return a constructed {@code AnyCall} object. Return None otherwise.
+  /// If @c E is a generic call (to ObjC method /function/block/etc),
+  /// return a constructed @c AnyCall object. Return None otherwise.
   static Optional<AnyCall> forExpr(const Expr *E) {
     if (const auto *ME = dyn_cast<ObjCMessageExpr>(E)) {
       return AnyCall(ME);
     } else if (const auto *CE = dyn_cast<CallExpr>(E)) {
       return AnyCall(CE);
     } else if (const auto *CXNE = dyn_cast<CXXNewExpr>(E)) {
       return AnyCall(CXNE);
     } else if (const auto *CXDE = dyn_cast<CXXDeleteExpr>(E)) {
       return AnyCall(CXDE);
     } else if (const auto *CXCE = dyn_cast<CXXConstructExpr>(E)) {
       return AnyCall(CXCE);
     } else if (const auto *CXCIE = dyn_cast<CXXInheritedCtorInitExpr>(E)) {
       return AnyCall(CXCIE);
     } else {
       return None;
     }
   }
 
-  /// If {@code D} is a callable (Objective-C method or a function), return
-  /// a constructed {@code AnyCall} object. Return None otherwise.
+  /// If @c D is a callable (Objective-C method or a function), return
+  /// a constructed @c AnyCall object. Return None otherwise.
   // FIXME: block support.
   static Optional<AnyCall> forDecl(const Decl *D) {
     if (const auto *FD = dyn_cast<FunctionDecl>(D)) {
       return AnyCall(FD);
     } else if (const auto *MD = dyn_cast<ObjCMethodDecl>(D)) {
       return AnyCall(MD);
     }
     return None;
QualType getReturnType(ASTContext &Ctx) const {
     case Allocator:
     case Deallocator:
       return cast<FunctionDecl>(D)->getReturnType();
     }
     llvm_unreachable("Unknown AnyCall::Kind");
   }
 
   /// \returns Function identifier if it is a named declaration,
-  /// {@code nullptr} otherwise.
+  /// @c nullptr otherwise.
   const IdentifierInfo *getIdentifier() const {
     if (const auto *ND = dyn_cast_or_null<NamedDecl>(D))
       return ND->getIdentifier();
     return nullptr;
   }
 
   const Decl *getDecl() const {
     return D;

clang/include/clang/Analysis/RetainSummaryManager.h

class RetainSummaryManager {
   /// Return a summary for Objective-C or CF object, or nullptr if not found.
   const RetainSummary *getSummaryForObjCOrCFObject(
     const FunctionDecl *FD,
     StringRef FName,
     QualType RetTy,
     const FunctionType *FT,
     bool &AllowAnnotations);
 
-  /// Apply the annotation of {@code pd} in function {@code FD}
-  /// to the resulting summary stored in out-parameter {@code Template}.
+  /// Apply the annotation of @c pd in function @c FD
+  /// to the resulting summary stored in out-parameter @c Template.
   /// \return whether an annotation was applied.
   bool applyParamAnnotationEffect(const ParmVarDecl *pd, unsigned parm_idx,
                                   const NamedDecl *FD,
                                   RetainSummaryTemplate &Template);
 
 public:
   RetainSummaryManager(ASTContext &ctx, bool trackObjCAndCFObjects,
                        bool trackOSObjects)
private:
   /// Note, we don't want to just stop tracking the value since we want the
   /// RetainCount checker to report leaks and use-after-free if SelfInit checker
   /// is turned off.
   void updateSummaryForReceiverUnconsumedSelf(const RetainSummary *&S);
 
   /// Set argument types for arguments which are not doing anything.
   void updateSummaryForArgumentTypes(const AnyCall &C, const RetainSummary *&RS);
 
-  /// Determine whether a declaration {@code D} of correspondent type (return
-  /// type for functions/methods) {@code QT} has any of the given attributes,
+  /// Determine whether a declaration @c D of correspondent type (return
+  /// type for functions/methods) @c QT has any of the given attributes,
   /// provided they pass necessary validation checks AND tracking the given
   /// attribute is enabled.
   /// Returns the object kind corresponding to the present attribute, or None,
   /// if none of the specified attributes are present.
   /// Crashes if passed an attribute which is not explicitly handled.
   template <class T>
   Optional<ObjKind> hasAnyEnabledAttrOf(const Decl *D, QualType QT);
 

clang/lib/Analysis/RetainSummaryManager.cpp

RetainSummaryManager::getRetEffectFromAnnotations(QualType RetTy,
   if (const auto *MD = dyn_cast<CXXMethodDecl>(D))
     for (const auto *PD : MD->overridden_methods())
       if (auto RE = getRetEffectFromAnnotations(RetTy, PD))
         return RE;
 
   return None;
 }
 
-/// \return Whether the chain of typedefs starting from {@code QT}
-/// has a typedef with a given name {@code Name}.
+/// \return Whether the chain of typedefs starting from @c QT
+/// has a typedef with a given name @c Name.
 static bool hasTypedefNamed(QualType QT,
                             StringRef Name) {
   while (auto *T = dyn_cast<TypedefType>(QT)) {
     const auto &Context = T->getDecl()->getASTContext();
     if (T->getDecl()->getIdentifier() == &Context.Idents.get(Name))
       return true;
     QT = T->getDecl()->getUnderlyingType();
   }

clang/lib/Sema/SemaDeclAttr.cpp

 template <typename T, typename... DiagnosticArgs>
 static const Sema::SemaDiagnosticBuilder&
 appendDiagnostics(const Sema::SemaDiagnosticBuilder &Bldr, T &&ExtraArg,
                   DiagnosticArgs &&... ExtraArgs) {
   return appendDiagnostics(Bldr << std::forward<T>(ExtraArg),
                            std::forward<DiagnosticArgs>(ExtraArgs)...);
 }
 
-/// Add an attribute {@code AttrType} to declaration {@code D}, provided that
-/// {@code PassesCheck} is true.
-/// Otherwise, emit diagnostic {@code DiagID}, passing in all parameters
-/// specified in {@code ExtraArgs}.
+/// Add an attribute @c AttrType to declaration @c D, provided that
+/// @c PassesCheck is true.
+/// Otherwise, emit diagnostic @c DiagID, passing in all parameters
+/// specified in @c ExtraArgs.
 template <typename AttrType, typename... DiagnosticArgs>
 static void handleSimpleAttributeOrDiagnose(Sema &S, Decl *D,
                                             const AttributeCommonInfo &CI,
                                             bool PassesCheck, unsigned DiagID,
                                             DiagnosticArgs &&... ExtraArgs) {
   if (!PassesCheck) {
     Sema::SemaDiagnosticBuilder DB = S.Diag(D->getBeginLoc(), DiagID);
     appendDiagnostics(DB, std::forward<DiagnosticArgs>(ExtraArgs)...);

clang/lib/StaticAnalyzer/Checkers/NonnullGlobalConstantsChecker.cpp

if (Constr) {
       // Assume that the variable is non-null.
       ProgramStateRef OutputState = State->assume(*Constr, true);
       C.addTransition(OutputState);
     }
   }
 }
 
 /// \param V loaded lvalue.
-/// \return whether {@code val} is a string-like const global.
+/// \return whether @c val is a string-like const global.
 bool NonnullGlobalConstantsChecker::isGlobalConstString(SVal V) const {
   Optional<loc::MemRegionVal> RegionVal = V.getAs<loc::MemRegionVal>();
   if (!RegionVal)
     return false;
   auto *Region = dyn_cast<VarRegion>(RegionVal->getAsRegion());
   if (!Region)
     return false;
   const VarDecl *Decl = Region->getDecl();
if (const auto *TT = dyn_cast<TypedefType>(T)) {
       Ty = AT->getModifiedType();
     } else {
       return false;
     }
   }
   return false;
 }
 
-/// \return whether {@code type} is extremely unlikely to be null
+/// \return whether @c type is extremely unlikely to be null
 bool NonnullGlobalConstantsChecker::isNonnullType(QualType Ty) const {
 
   if (Ty->isPointerType() && Ty->getPointeeType()->isCharType())
     return true;
 
   if (auto *T = dyn_cast<ObjCObjectPointerType>(Ty)) {
     return T->getInterfaceDecl() &&
       T->getInterfaceDecl()->getIdentifier() == NSStringII;

clang/lib/StaticAnalyzer/Checkers/ObjCAutoreleaseWriteChecker.cpp

 //===- ObjCAutoreleaseWriteChecker.cpp ----------------------------*- C++ -*-==//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
 // This file defines ObjCAutoreleaseWriteChecker which warns against writes
 // into autoreleased out parameters which cause crashes.
-// An example of a problematic write is a write to {@code error} in the example
+// An example of a problematic write is a write to @c error in the example
 // below:
 //
 // - (BOOL) mymethod:(NSError *__autoreleasing *)error list:(NSArray*) list {
 //     [list enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
 //       NSString *myString = obj;
 //       if ([myString isEqualToString:@"error"] && error)
 //         *error = [NSError errorWithDomain:@"MyDomain" code:-1];
 //     }];

clang/lib/StaticAnalyzer/Checkers/RetainCountChecker/RetainCountDiagnostics.cpp

 static std::string getPrettyTypeName(QualType QT) {
   QualType PT = QT->getPointeeType();
   if (!PT.isNull() && !QT->getAs<TypedefType>())
     if (const auto *RD = PT->getAsCXXRecordDecl())
       return std::string(RD->getName());
   return QT.getAsString();
 }
 
-/// Write information about the type state change to {@code os},
+/// Write information about the type state change to @c os,
 /// return whether the note should be generated.
 static bool shouldGenerateNote(llvm::raw_string_ostream &os,
                                const RefVal *PrevT,
                                const RefVal &CurrV,
                                bool DeallocSent) {
   // Get the previous type state.
   RefVal PrevV = *PrevT;
 
case RefVal::ReturnedNotOwned:
       return true;
 
     default:
       return false;
     }
   return true;
 }
 
-/// Finds argument index of the out paramter in the call {@code S}
-/// corresponding to the symbol {@code Sym}.
+/// Finds argument index of the out paramter in the call @c S
+/// corresponding to the symbol @c Sym.
 /// If none found, returns None.
 static Optional<unsigned> findArgIdxOfSymbol(ProgramStateRef CurrSt,
                                              const LocationContext *LCtx,
                                              SymbolRef &Sym,
                                              Optional<CallEventRef<>> CE) {
   if (!CE)
     return None;
 

clang/lib/StaticAnalyzer/Checkers/RunLoopAutoreleaseLeakChecker.cpp

public:
   void checkASTCodeBody(const Decl *D,
                         AnalysisManager &AM,
                         BugReporter &BR) const;
 
 };
 
 } // end anonymous namespace
 
-/// \return Whether {@code A} occurs before {@code B} in traversal of
-/// {@code Parent}.
+/// \return Whether @c A occurs before @c B in traversal of
+/// @c Parent.
 /// Conceptually a very incomplete/unsound approximation of happens-before
 /// relationship (A is likely to be evaluated before B),
 /// but useful enough in this case.
 static bool seenBefore(const Stmt *Parent, const Stmt *A, const Stmt *B) {
   for (const Stmt *C : Parent->children()) {
     if (!C) continue;
 
     if (C == A)

clang/lib/StaticAnalyzer/Core/BugReporter.cpp

static void CompactMacroExpandedPieces(PathPieces &path,
 
   // Now take the pieces and construct a new PathDiagnostic.
   path.clear();
 
   path.insert(path.end(), Pieces.begin(), Pieces.end());
 }
 
 /// Generate notes from all visitors.
-/// Notes associated with {@code ErrorNode} are generated using
-/// {@code getEndPath}, and the rest are generated with {@code VisitNode}.
+/// Notes associated with @c ErrorNode are generated using
+/// @c getEndPath, and the rest are generated with @c VisitNode.
 static std::unique_ptr<VisitorsDiagnosticsTy>
 generateVisitorsDiagnostics(PathSensitiveBugReport *R,
                             const ExplodedNode *ErrorNode,
                             BugReporterContext &BRC) {
   std::unique_ptr<VisitorsDiagnosticsTy> Notes =
       std::make_unique<VisitorsDiagnosticsTy>();
   PathSensitiveBugReport::VisitorList visitors;
 
   // Run visitors on all nodes starting from the node *before* the last one.
-  // The last node is reserved for notes generated with {@code getEndPath}.
+  // The last node is reserved for notes generated with @c getEndPath.
   const ExplodedNode *NextNode = ErrorNode->getFirstPred();
   while (NextNode) {
 
     // At each iteration, move all visitors from report to visitor list. This is
     // important, because the Profile() functions of the visitors make sure that
     // a visitor isn't added multiple times for the same node, but it's fine
     // to add the a visitor with Profile() for different nodes (e.g. tracking
     // a region at different points of the symbolic execution).

clang/lib/StaticAnalyzer/Core/BugReporterVisitors.cpp

static const MemRegion *getLocationRegionIfReference(const Expr *E,
   // for example, references from FieldRegions:
   //   struct Wrapper { int &ref; };
   //   Wrapper w = { *(int *)0 };
   //   w.ref = 1;
 
   return nullptr;
 }
 
-/// \return A subexpression of {@code Ex} which represents the
+/// \return A subexpression of @c Ex which represents the
 /// expression-of-interest.
 static const Expr *peelOffOuterExpr(const Expr *Ex,
                                     const ExplodedNode *N) {
   Ex = Ex->IgnoreParenCasts();
   if (const auto *FE = dyn_cast<FullExpr>(Ex))
     return peelOffOuterExpr(FE->getSubExpr(), N);
   if (const auto *OVE = dyn_cast<OpaqueValueExpr>(Ex))
     return peelOffOuterExpr(OVE->getSourceExpr(), N);

clang/lib/StaticAnalyzer/Core/ExprEngine.cpp

for (const auto &EQ : EQClasses) {
           return true;
       }
     }
     return false;
   }
 
   /// \p PreCallback: callback before break.
   /// \p PostCallback: callback after break.
-  /// \p Stop: stop iteration if returns {@code true}
-  /// \return Whether {@code Stop} ever returned {@code true}.
+  /// \p Stop: stop iteration if returns @c true
+  /// \return Whether @c Stop ever returned @c true.
   static bool traverseHiddenNodes(
       const ExplodedNode *N,
       llvm::function_ref<void(const ExplodedNode *)> PreCallback,
       llvm::function_ref<void(const ExplodedNode *)> PostCallback,
       llvm::function_ref<bool(const ExplodedNode *)> Stop) {
     while (true) {
       PreCallback(N);
       if (Stop(N))

clang/lib/StaticAnalyzer/Core/PlistDiagnostics.cpp

void ReportNote(raw_ostream &o, const PathDiagnosticNotePiece& P,
                   unsigned indent);
 
   void ReportPopUp(raw_ostream &o, const PathDiagnosticPopUpPiece &P,
                    unsigned indent);
 };
 
 } // end of anonymous namespace
 
-/// Print coverage information to output stream {@code o}.
-/// May modify the used list of files {@code Fids} by inserting new ones.
+/// Print coverage information to output stream @c o.
+/// May modify the used list of files @c Fids by inserting new ones.
 static void printCoverage(const PathDiagnostic *D,
                           unsigned InputIndentLevel,
                           SmallVectorImpl<FileID> &Fids,
                           FIDMap &FM,
                           llvm::raw_fd_ostream &o);
 
 static Optional<StringRef> getExpandedMacro(
     SourceLocation MacroLoc, const cross_tu::CrossTranslationUnitContext &CTU,
void PlistPrinter::ReportPopUp(raw_ostream &o,
   --indent;
   Indent(o, indent) << "</dict>\n";
 }
 
 //===----------------------------------------------------------------------===//
 // Static function definitions.
 //===----------------------------------------------------------------------===//
 
-/// Print coverage information to output stream {@code o}.
-/// May modify the used list of files {@code Fids} by inserting new ones.
+/// Print coverage information to output stream @c o.
+/// May modify the used list of files @c Fids by inserting new ones.
 static void printCoverage(const PathDiagnostic *D,
                           unsigned InputIndentLevel,
                           SmallVectorImpl<FileID> &Fids,
                           FIDMap &FM,
                           llvm::raw_fd_ostream &o) {
   unsigned IndentLevel = InputIndentLevel;
 
   Indent(o, IndentLevel) << "<key>ExecutedLines</key>\n";

llvm/include/llvm/Support/GraphWriter.h

raw_ostream &WriteGraph(raw_ostream &O, const GraphType &G,
   // Emit the graph.
   W.writeGraph(Title.str());
 
   return O;
 }
 
 std::string createGraphFilename(const Twine &Name, int &FD);
 
-/// Writes graph into a provided {@code Filename}.
-/// If {@code Filename} is empty, generates a random one.
+/// Writes graph into a provided @c Filename.
+/// If @c Filename is empty, generates a random one.
 /// \return The resulting filename, or an empty string if writing
 /// failed.
 template <typename GraphType>
 std::string WriteGraph(const GraphType &G, const Twine &Name,
                        bool ShortNames = false,
                        const Twine &Title = "",
                        std::string Filename = "") {
   int FD;