Remove \brief commands from doxygen comments.

We've been running doxygen with the autobrief option for a couple of
years now. This makes the \brief markers into our comments
redundant. Since they are a visual distraction and we don't want to
encourage more \brief markers in new code either, this patch removes
them all.

Patch produced by

      for i in $(git grep -l '\\brief'); do perl -pi -e 's/\\brief //g' $i & done

Author: adrian-prantl

benchmark/single-source/Hash.swift

@@ -21,15 +21,15 @@ public let HashTest = BenchmarkInfo(
   tags: [.validation, .algorithm])
 
 class Hash {
-  /// \brief C'tor.
+  /// C'tor.
   init(_ bs: Int) {
     blocksize = bs
     messageLength = 0
     dataLength = 0
     assert(blocksize <= 64, "Invalid block size")
   }
 
-  /// \brief Add the bytes in \p Msg to the hash.
+  /// Add the bytes in \p Msg to the hash.
   func update(_ Msg: String) {
     for c in Msg.unicodeScalars {
       data[dataLength] = UInt8(ascii: c)
@@ -39,7 +39,7 @@ class Hash {
     }
   }
 
-  /// \brief Add the bytes in \p Msg to the hash.
+  /// Add the bytes in \p Msg to the hash.
   func update(_ Msg: [UInt8]) {
     for c in Msg {
       data[dataLength] = c
@@ -65,7 +65,7 @@ class Hash {
   final var data = [UInt8](repeating: 0, count: 64)
   final var blocksize: Int
 
-  /// \brief Hash the internal data.
+  /// Hash the internal data.
   func hash() {
     fatalError("Pure virtual")
   }
@@ -78,7 +78,7 @@ class Hash {
     fatalError("Pure virtual")
   }
 
-  /// \brief Blow the data to fill the block.
+  /// Blow the data to fill the block.
   func fillBlock() {
     fatalError("Pure virtual")
   }
@@ -87,7 +87,7 @@ class Hash {
   final
   var HexTblFast : [UInt8] = [48,49,50,51,52,53,54,55,56,57,97,98,99,100,101,102]
 
-  /// \brief Convert a 4-byte integer to a hex string.
+  /// Convert a 4-byte integer to a hex string.
   final
   func toHex(_ In: UInt32) -> String {
     var In = In
@@ -110,13 +110,13 @@ class Hash {
     }
   }
 
-  /// \brief Left-rotate \p x by \p c.
+  /// Left-rotate \p x by \p c.
   final
   func rol(_ x: UInt32, _ c: UInt32) -> UInt32 {
     return x &<< c | x &>> (32 &- c)
   }
 
-  /// \brief Right-rotate \p x by \p c.
+  /// Right-rotate \p x by \p c.
   final
   func ror(_ x: UInt32, _ c: UInt32) -> UInt32 {
     return x &>> c | x &<< (32 &- c)

docs/TextFormatting.rst

@@ -131,11 +131,11 @@ Via compiler magic, *everything* conforms to the ``CustomDebugStringConvertible`
 protocol. To change the debug representation for a type, you don't
 need to declare conformance: simply give the type a ``debugFormat()``::
 
-  /// \brief A thing that can be printed in the REPL and the Debugger
+  /// A thing that can be printed in the REPL and the Debugger
   protocol CustomDebugStringConvertible {
     typealias DebugRepresentation : TextOutputStreamable = String
 
-    /// \brief Produce a textual representation for the REPL and
+    /// Produce a textual representation for the REPL and
     /// Debugger.
     func debugFormat() -> DebugRepresentation
   }
@@ -169,19 +169,19 @@ Conformance to ``CustomStringConvertible`` is explicit, but if you want to use t
 need to do is declare conformance to ``CustomStringConvertible``; there's nothing to
 implement::
 
-  /// \brief A thing that can be print()ed and toString()ed.
+  /// A thing that can be print()ed and toString()ed.
   protocol CustomStringConvertible : CustomDebugStringConvertible {
     typealias PrintRepresentation : TextOutputStreamable = DebugRepresentation
 
-    /// \brief produce a "pretty" textual representation.
+    /// produce a "pretty" textual representation.
     ///
     /// In general you can return a String here, but if you need more
     /// control, return a custom TextOutputStreamable type
     func format() -> PrintRepresentation {
       return debugFormat()
     }
 
-    /// \brief Simply convert to String
+    /// Simply convert to String
     ///
     /// You'll never want to reimplement this
     func toString() -> String {

docs/doxygen.cfg.in

@@ -138,7 +138,7 @@ SHORT_NAMES            = NO
 # comments will behave just like the Qt-style comments (thus requiring an
 # explicit @brief command for a brief description.
 
-JAVADOC_AUTOBRIEF      = NO
+JAVADOC_AUTOBRIEF      = YES
 
 # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
 # treat a multi-line C++ special comment block (i.e. a block of //! or ///

include/swift/ABI/Metadata.h

@@ -1957,7 +1957,7 @@ struct TargetGenericBoxHeapMetadata : public TargetBoxHeapMetadata<Runtime> {
 };
 using GenericBoxHeapMetadata = TargetGenericBoxHeapMetadata<InProcess>;
 
-/// \brief The control structure of a generic or resilient protocol
+/// The control structure of a generic or resilient protocol
 /// conformance witness.
 ///
 /// Resilient conformances must use a pattern where new requirements
@@ -2008,7 +2008,7 @@ struct TargetResilientWitnessTable final
 };
 using ResilientWitnessTable = TargetResilientWitnessTable<InProcess>;
 
-/// \brief The control structure of a generic or resilient protocol
+/// The control structure of a generic or resilient protocol
 /// conformance, which is embedded in the protocol conformance descriptor.
 ///
 /// Witness tables need to be instantiated at runtime in these cases:

include/swift/AST/ASTContext.h

@@ -112,16 +112,16 @@ namespace syntax {
   class SyntaxArena;
 }
 
-/// \brief The arena in which a particular ASTContext allocation will go.
+/// The arena in which a particular ASTContext allocation will go.
 enum class AllocationArena {
-  /// \brief The permanent arena, which is tied to the lifetime of
+  /// The permanent arena, which is tied to the lifetime of
   /// the ASTContext.
   ///
   /// All global declarations and types need to be allocated into this arena.
   /// At present, everything that is not a type involving a type variable is
   /// allocated in this arena.
   Permanent,
-  /// \brief The constraint solver's temporary arena, which is tied to the
+  /// The constraint solver's temporary arena, which is tied to the
   /// lifetime of a particular instance of the constraint solver.
   ///
   /// Any type involving a type variable is allocated in this arena.
@@ -144,14 +144,14 @@ enum class KnownFoundationEntity {
 /// entity name.
 Optional<KnownFoundationEntity> getKnownFoundationEntity(StringRef name);
 
-/// \brief Introduces a new constraint checker arena, whose lifetime is
+/// Introduces a new constraint checker arena, whose lifetime is
 /// tied to the lifetime of this RAII object.
 class ConstraintCheckerArenaRAII {
   ASTContext &Self;
   void *Data;
 
 public:
-  /// \brief Introduces a new constraint checker arena, supplanting any
+  /// Introduces a new constraint checker arena, supplanting any
   /// existing constraint checker arena.
   ///
   /// \param self The ASTContext into which this constraint checker arena
@@ -216,13 +216,13 @@ class ASTContext final {
   /// it before being set to null.
   UnifiedStatsReporter *Stats = nullptr;
 
-  /// \brief The language options used for translation.
+  /// The language options used for translation.
   LangOptions &LangOpts;
 
-  /// \brief The search path options used by this AST context.
+  /// The search path options used by this AST context.
   SearchPathOptions &SearchPathOpts;
 
-  /// \brief The source manager object.
+  /// The source manager object.
   SourceManager &SourceMgr;
 
   /// Diags - The diagnostics engine.
@@ -252,7 +252,7 @@ class ASTContext final {
 #define IDENTIFIER_WITH_NAME(Name, IdStr) Identifier Id_##Name;
 #include "swift/AST/KnownIdentifiers.def"
 
-  /// \brief The list of external definitions imported by this context.
+  /// The list of external definitions imported by this context.
   llvm::SetVector<Decl *> ExternalDefinitions;
 
   /// FIXME: HACK HACK HACK
@@ -270,7 +270,7 @@ class ASTContext final {
   llvm::StringMap<Type> RemappedTypes;
 
 private:
-  /// \brief The current generation number, which reflects the number of
+  /// The current generation number, which reflects the number of
   /// times that external modules have been loaded.
   ///
   /// Various places in the AST, such as the set of extensions associated with
@@ -289,7 +289,7 @@ class ASTContext final {
   /// Cache of module names that fail the 'canImport' test in this context.
   llvm::SmallPtrSet<Identifier, 8> FailedModuleImportNames;
 
-  /// \brief Retrieve the allocator for the given arena.
+  /// Retrieve the allocator for the given arena.
   llvm::BumpPtrAllocator &
   getAllocator(AllocationArena arena = AllocationArena::Permanent) const;
 
@@ -630,7 +630,7 @@ class ASTContext final {
   /// Does any proper bookkeeping to keep all module loaders up to date as well.
   void addSearchPath(StringRef searchPath, bool isFramework, bool isSystem);
 
-  /// \brief Adds a module loader to this AST context.
+  /// Adds a module loader to this AST context.
   ///
   /// \param loader The new module loader, which will be added after any
   ///               existing module loaders.
@@ -640,7 +640,7 @@ class ASTContext final {
   void addModuleLoader(std::unique_ptr<ModuleLoader> loader,
                        bool isClang = false);
 
-  /// \brief Load extensions to the given nominal type from the external
+  /// Load extensions to the given nominal type from the external
   /// module loaders.
   ///
   /// \param nominal The nominal type whose extensions should be loaded.
@@ -650,7 +650,7 @@ class ASTContext final {
   /// one.
   void loadExtensions(NominalTypeDecl *nominal, unsigned previousGeneration);
 
-  /// \brief Load the methods within the given class that produce
+  /// Load the methods within the given class that produce
   /// Objective-C class or instance methods with the given selector.
   ///
   /// \param classDecl The class in which we are searching for @objc methods.
@@ -675,7 +675,7 @@ class ASTContext final {
                        unsigned previousGeneration,
                        llvm::TinyPtrVector<AbstractFunctionDecl *> &methods);
 
-  /// \brief Retrieve the Clang module loader for this ASTContext.
+  /// Retrieve the Clang module loader for this ASTContext.
   ///
   /// If there is no Clang module loader, returns a null pointer.
   /// The loader is owned by the AST context.
@@ -686,7 +686,7 @@ class ASTContext final {
   /// Does nothing in non-asserts (NDEBUG) builds.
   void verifyAllLoadedModules() const;
 
-  /// \brief Check whether the module with a given name can be imported without
+  /// Check whether the module with a given name can be imported without
   /// importing it.
   ///
   /// Note that even if this check succeeds, errors may still occur if the
@@ -700,7 +700,7 @@ class ASTContext final {
 
   ModuleDecl *getLoadedModule(Identifier ModuleName) const;
 
-  /// \brief Attempts to load a module into this ASTContext.
+  /// Attempts to load a module into this ASTContext.
   ///
   /// If a module by this name has already been loaded, the existing module will
   /// be returned.
@@ -720,7 +720,7 @@ class ASTContext final {
     return const_cast<ASTContext *>(this)->getStdlibModule(false);
   }
 
-  /// \brief Retrieve the current generation number, which reflects the
+  /// Retrieve the current generation number, which reflects the
   /// number of times a module import has caused mass invalidation of
   /// lookup tables.
   ///
@@ -729,14 +729,14 @@ class ASTContext final {
   /// with a nominal type.
   unsigned getCurrentGeneration() const { return CurrentGeneration; }
 
-  /// \brief Increase the generation number, implying that various lookup
+  /// Increase the generation number, implying that various lookup
   /// tables have been significantly altered by the introduction of a new
   /// module import.
   ///
   /// \returns the previous generation number.
   unsigned bumpGeneration() { return CurrentGeneration++; }
 
-  /// \brief Produce a "normal" conformance for a nominal type.
+  /// Produce a "normal" conformance for a nominal type.
   NormalProtocolConformance *
   getConformance(Type conformingType,
                  ProtocolDecl *protocol,
@@ -785,7 +785,7 @@ class ASTContext final {
   std::vector<ValueDecl*>
   takeDelayedMissingWitnesses(NormalProtocolConformance *conformance);
 
-  /// \brief Produce a specialized conformance, which takes a generic
+  /// Produce a specialized conformance, which takes a generic
   /// conformance and substitutions written in terms of the generic
   /// conformance's signature.
   ///
@@ -800,7 +800,7 @@ class ASTContext final {
                             ProtocolConformance *generic,
                             SubstitutionMap substitutions);
 
-  /// \brief Produce an inherited conformance, for subclasses of a type
+  /// Produce an inherited conformance, for subclasses of a type
   /// that already conforms to a protocol.
   ///
   /// \param type The type for which we are retrieving the conformance.
@@ -848,10 +848,10 @@ class ASTContext final {
                                               const IterableDeclContext *idc,
                                               LazyMemberLoader *lazyLoader);
 
-  /// \brief Returns memory usage of this ASTContext.
+  /// Returns memory usage of this ASTContext.
   size_t getTotalMemory() const;
 
-  /// \brief Returns memory used exclusively by constraint solver.
+  /// Returns memory used exclusively by constraint solver.
   size_t getSolverMemory() const;
 
   /// Complain if @objc or dynamic is used without importing Foundation.

include/swift/AST/ASTMangler.h

@@ -198,7 +198,7 @@ class ASTMangler : public Mangler {
 
   void bindGenericParameters(CanGenericSignature sig);
 
-  /// \brief Mangles a sugared type iff we are mangling for the debugger.
+  /// Mangles a sugared type iff we are mangling for the debugger.
   template <class T> void appendSugaredType(Type type) {
     assert(DWARFMangling &&
            "sugared types are only legal when mangling for the debugger");

include/swift/AST/ASTNode.h

@@ -38,16 +38,16 @@ namespace swift {
 
     SourceRange getSourceRange() const;
 
-    /// \brief Return the location of the start of the statement.
+    /// Return the location of the start of the statement.
     SourceLoc getStartLoc() const;
 
-    /// \brief Return the location of the end of the statement.
+    /// Return the location of the end of the statement.
     SourceLoc getEndLoc() const;
 
     void walk(ASTWalker &Walker);
     void walk(ASTWalker &&walker) { walk(walker); }
 
-    /// \brief get the underlying entity as a decl context if it is one,
+    /// get the underlying entity as a decl context if it is one,
     /// otherwise, return nullptr;
     DeclContext *getAsDeclContext() const;