Doxygenize the documentation comments

src/IceELFSection.h

Index: src/IceELFSection.h
diff --git a/src/IceELFSection.h b/src/IceELFSection.h
index a79a9fbbcc95875906f2156b7a201b6b9d1f7709..34664fcef634e5dc115af3d1909f63a6824f5d91 100644
--- a/src/IceELFSection.h
+++ b/src/IceELFSection.h
@@ -26,7 +26,7 @@ namespace Ice {
 class ELFStreamer;
 class ELFStringTableSection;
 
-// Base representation of an ELF section.
+/// Base representation of an ELF section.
 class ELFSection {
   ELFSection() = delete;
   ELFSection(const ELFSection &) = delete;
@@ -35,10 +35,10 @@ class ELFSection {
 public:
   virtual ~ELFSection() = default;
 
-  // Sentinel value for a section number/index for before the final
-  // section index is actually known. The dummy NULL section will be assigned
-  // number 0, and it is referenced by the dummy 0-th symbol in the symbol
-  // table, so use max() instead of 0.
+  /// Sentinel value for a section number/index for before the final
+  /// section index is actually known. The dummy NULL section will be assigned
+  /// number 0, and it is referenced by the dummy 0-th symbol in the symbol
+  /// table, so use max() instead of 0.
   enum { NoSectionNumber = std::numeric_limits<SizeT>::max() };
 
   // Constructs an ELF section, filling in fields that will be known

[Karl, 2015/07/06 18:08:48]

Why not here?

[ascull, 2015/07/06 19:29:09]

Done.

@@ -53,7 +53,7 @@ public:
     Header.sh_entsize = ShEntsize;
   }
 
-  // Set the section number/index after it is finally known.
+  /// Set the section number/index after it is finally known.
   void setNumber(SizeT N) {
     // Should only set the number once: from NoSectionNumber -> N.
     assert(Number == NoSectionNumber);
@@ -79,24 +79,24 @@ public:
 
   Elf64_Xword getSectionAlign() const { return Header.sh_addralign; }
 
-  // Write the section header out with the given streamer.
+  /// Write the section header out with the given streamer.
   template <bool IsELF64> void writeHeader(ELFStreamer &Str);
 
 protected:
-  // Name of the section in convenient string form (instead of a index
-  // into the Section Header String Table, which is not known till later).
+  /// Name of the section in convenient string form (instead of a index
+  /// into the Section Header String Table, which is not known till later).
   const IceString Name;
 
   // The fields of the header. May only be partially initialized, but should
   // be fully initialized before writing.
   Elf64_Shdr Header;
 
-  // The number of the section after laying out sections.
+  /// The number of the section after laying out sections.
   SizeT Number = NoSectionNumber;
 };
 
-// Models text/code sections. Code is written out incrementally and the
-// size of the section is then updated incrementally.
+/// Models text/code sections. Code is written out incrementally and the
+/// size of the section is then updated incrementally.
 class ELFTextSection : public ELFSection {
   ELFTextSection() = delete;
   ELFTextSection(const ELFTextSection &) = delete;
@@ -108,9 +108,9 @@ public:
   void appendData(ELFStreamer &Str, const llvm::StringRef MoreData);
 };
 
-// Models data/rodata sections. Data is written out incrementally and the
-// size of the section is then updated incrementally.
-// Some rodata sections may have fixed entsize and duplicates may be mergeable.
+/// Models data/rodata sections. Data is written out incrementally and the
+/// size of the section is then updated incrementally.
+/// Some rodata sections may have fixed entsize and duplicates may be mergeable.
 class ELFDataSection : public ELFSection {
   ELFDataSection() = delete;
   ELFDataSection(const ELFDataSection &) = delete;
@@ -126,9 +126,9 @@ public:
   void appendRelocationOffset(ELFStreamer &Str, bool IsRela,
                               RelocOffsetT RelocOffset);
 
-  // Pad the next section offset for writing data elements to the requested
-  // alignment. If the section is NOBITS then do not actually write out
-  // the padding and only update the section size.
+  /// Pad the next section offset for writing data elements to the requested
+  /// alignment. If the section is NOBITS then do not actually write out
+  /// the padding and only update the section size.
   void padToAlignment(ELFStreamer &Str, Elf64_Xword Align);
 };
 
@@ -140,8 +140,8 @@ struct ELFSym {
   ELFSection *Section;
   SizeT Number;
 
-  // Sentinel value for symbols that haven't been assigned a number yet.
-  // The dummy 0-th symbol will be assigned number 0, so don't use that.
+  /// Sentinel value for symbols that haven't been assigned a number yet.
+  /// The dummy 0-th symbol will be assigned number 0, so don't use that.
   enum { UnknownNumber = std::numeric_limits<SizeT>::max() };
 
   void setNumber(SizeT N) {
@@ -155,8 +155,8 @@ struct ELFSym {
   }
 };
 
-// Models a symbol table. Symbols may be added up until updateIndices is
-// called. At that point the indices of each symbol will be finalized.
+/// Models a symbol table. Symbols may be added up until updateIndices is
+/// called. At that point the indices of each symbol will be finalized.
 class ELFSymbolTableSection : public ELFSection {
   ELFSymbolTableSection() = delete;
   ELFSymbolTableSection(const ELFSymbolTableSection &) = delete;
@@ -169,16 +169,16 @@ public:
       : ELFSection(Name, ShType, ShFlags, ShAddralign, ShEntsize),
         NullSymbol(nullptr) {}
 
-  // Create initial entry for a symbol when it is defined.
-  // Each entry should only be defined once.
-  // We might want to allow Name to be a dummy name initially, then
-  // get updated to the real thing, since Data initializers are read
-  // before the bitcode's symbol table is read.
+  /// Create initial entry for a symbol when it is defined.
+  /// Each entry should only be defined once.
+  /// We might want to allow Name to be a dummy name initially, then
+  /// get updated to the real thing, since Data initializers are read
+  /// before the bitcode's symbol table is read.
   void createDefinedSym(const IceString &Name, uint8_t Type, uint8_t Binding,
                         ELFSection *Section, RelocOffsetT Offset, SizeT Size);
 
-  // Note that a symbol table entry needs to be created for the given
-  // symbol because it is undefined.
+  /// Note that a symbol table entry needs to be created for the given
+  /// symbol because it is undefined.
   void noteUndefinedSym(const IceString &Name, ELFSection *NullSection);
 
   const ELFSym *findSymbol(const IceString &Name) const;
@@ -212,7 +212,7 @@ private:
   SymMap GlobalSymbols;
 };
 
-// Models a relocation section.
+/// Models a relocation section.
 class ELFRelocationSection : public ELFSection {
   ELFRelocationSection() = delete;
   ELFRelocationSection(const ELFRelocationSection &) = delete;
@@ -230,11 +230,11 @@ public:
     RelatedSection = Section;
   }
 
-  // Track additional relocations which start out relative to offset 0,
-  // but should be adjusted to be relative to BaseOff.
+  /// Track additional relocations which start out relative to offset 0,
+  /// but should be adjusted to be relative to BaseOff.
   void addRelocations(RelocOffsetT BaseOff, const FixupRefList &FixupRefs);
 
-  // Track a single additional relocation.
+  /// Track a single additional relocation.
   void addRelocation(const AssemblerFixup &Fixup) { Fixups.push_back(Fixup); }
 
   size_t getSectionDataSize() const;
@@ -250,12 +250,12 @@ private:
   FixupList Fixups;
 };
 
-// Models a string table.  The user will build the string table by
-// adding strings incrementally.  At some point, all strings should be
-// known and doLayout() should be called. After that, no other
-// strings may be added.  However, the final offsets of the strings
-// can be discovered and used to fill out section headers and symbol
-// table entries.
+/// Models a string table.  The user will build the string table by
+/// adding strings incrementally.  At some point, all strings should be
+/// known and doLayout() should be called. After that, no other
+/// strings may be added.  However, the final offsets of the strings
+/// can be discovered and used to fill out section headers and symbol
+/// table entries.
 class ELFStringTableSection : public ELFSection {
   ELFStringTableSection() = delete;
   ELFStringTableSection(const ELFStringTableSection &) = delete;
@@ -264,18 +264,18 @@ class ELFStringTableSection : public ELFSection {
 public:
   using ELFSection::ELFSection;
 
-  // Add a string to the table, in preparation for final layout.
+  /// Add a string to the table, in preparation for final layout.
   void add(const IceString &Str);
 
-  // Finalizes the layout of the string table and fills in the section Data.
+  /// Finalizes the layout of the string table and fills in the section Data.
   void doLayout();
 
-  // The first byte of the string table should be \0, so it is an
-  // invalid index.  Indices start out as unknown until layout is complete.
+  /// The first byte of the string table should be \0, so it is an
+  /// invalid index.  Indices start out as unknown until layout is complete.
   enum { UnknownIndex = 0 };
 
-  // Grabs the final index of a string after layout. Returns UnknownIndex
-  // if the string's index is not found.
+  /// Grabs the final index of a string after layout. Returns UnknownIndex
+  /// if the string's index is not found.
   size_t getIndex(const IceString &Str) const;
 
   llvm::StringRef getSectionData() const {
@@ -289,19 +289,19 @@ public:
 private:
   bool isLaidOut() const { return !StringData.empty(); }
 
-  // Strings can share a string table entry if they share the same
-  // suffix.  E.g., "pop" and "lollipop" can both use the characters
-  // in "lollipop", but "pops" cannot, and "unpop" cannot either.
-  // Though, "pop", "lollipop", and "unpop" share "pop" as the suffix,
-  // "pop" can only share the characters with one of them.
+  /// Strings can share a string table entry if they share the same
+  /// suffix.  E.g., "pop" and "lollipop" can both use the characters
+  /// in "lollipop", but "pops" cannot, and "unpop" cannot either.
+  /// Though, "pop", "lollipop", and "unpop" share "pop" as the suffix,
+  /// "pop" can only share the characters with one of them.
   struct SuffixComparator {
     bool operator()(const IceString &StrA, const IceString &StrB) const;
   };
 
   typedef std::map<IceString, size_t, SuffixComparator> StringToIndexType;
 
-  // Track strings to their index.  Index will be UnknownIndex if not
-  // yet laid out.
+  /// Track strings to their index.  Index will be UnknownIndex if not
+  /// yet laid out.
   StringToIndexType StringToIndexMap;
 
   typedef std::vector<uint8_t> RawDataType;