From 381e92c66a98ee766ea53039b0cd8ce3bde7be2d Mon Sep 17 00:00:00 2001
From: Daniel Dunbar <daniel@zuster.org>
Date: Tue, 23 Jun 2009 23:02:31 +0000
Subject: [PATCH] Add comments for the MCStreamer interface.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@74019 91177308-0d34-0410-b5e6-96231b3b80d8
---
 include/llvm/MC/MCStreamer.h | 83 +++++++++++++++++++++++++++++++++---
 1 file changed, 77 insertions(+), 6 deletions(-)

diff --git a/include/llvm/MC/MCStreamer.h b/include/llvm/MC/MCStreamer.h
index 909f0a585db..ce495dcc13d 100644
--- a/include/llvm/MC/MCStreamer.h
+++ b/include/llvm/MC/MCStreamer.h
@@ -34,26 +34,97 @@ namespace llvm {
     MCStreamer(const MCStreamer&); // DO NOT IMPLEMENT
     MCStreamer &operator=(const MCStreamer&); // DO NOT IMPLEMENT
 
-  public:
+  protected:
     MCStreamer(MCContext &Ctx);
+
+  public:
     virtual ~MCStreamer();
 
     MCContext &getContext() const { return Context; }
 
-    virtual void SwitchSection(MCSection *Sect) = 0;
+    /// SwitchSection - Set the current section where code is being emitted to
+    /// @param Section.
+    ///
+    /// This corresponds to assembler directives like .section, .text, etc.
+    virtual void SwitchSection(MCSection *Section) = 0;
 
-    virtual void EmitSymbol(MCSymbol *Sym);
-    virtual void EmitSymbolAssignment(MCSymbol *Sym, const MCImm &Value) = 0;
-    virtual void EmitSymbolAttribute(MCSymbol *Sym, 
-                                     SymbolAttr Attr) = 0;
+    /// EmitLabel - Emit a label for @param Symbol into the current section.
+    ///
+    /// This corresponds to an assembler statement such as:
+    ///   foo:
+    ///
+    /// @param Symbol - The symbol to emit. A given symbol should only be
+    /// emitted as a label once, and symbols emitted as a label should never be
+    /// used in an assignment.
+    //
+    // FIXME: What to do about the current section? Should we get rid of the
+    // symbol section in the constructor and initialize it here?
+    virtual void EmitLabel(MCSymbol *Symbol);
 
+    /// EmitAssignment - Emit an assignment of @param Value to @param Symbol.
+    ///
+    /// This corresponds to an assembler statement such as:
+    ///  symbol = value
+    ///
+    /// The assignment generates no code, but has the side effect of binding the
+    /// value in the current context. For the assembly streamer, this prints the
+    /// binding into the .s file.
+    ///
+    /// @param Symbol - The symbol being assigned to.
+    /// @param Value - The value for the symbol.
+    /// @param MakeAbsolute - If true, then the symbol should be given the
+    /// absolute value of @param Value, even if @param Value would be
+    /// relocatable expression. This corresponds to the ".set" directive.
+    virtual void EmitAssignment(MCSymbol *Symbol, const MCImm &Value,
+                                bool MakeAbsolute = false) = 0;
+
+    /// EmitSymbolAttribute - Add the given @param Attribute to @param Symbol.
+    //
+    // FIXME: This doesn't make much sense, could we just have attributes be on
+    // the symbol and make the printer smart enough to add the right symbols?
+    // This should work as long as the order of attributes in the file doesn't
+    // matter.
+    virtual void EmitSymbolAttribute(MCSymbol *Symbol, 
+                                     SymbolAttr Attribute) = 0;
+
+    /// EmitBytes - Emit @param Length bytes starting at @param Data into the
+    /// output.
+    ///
+    /// This is used to implement assembler directives such as .byte, .ascii,
+    /// etc.
     virtual void EmitBytes(const char *Data, unsigned Length) = 0;
+
+    /// EmitValue - Emit the expression @param Value into the output as a native
+    /// integer of the given @param Size bytes.
+    ///
+    /// This is used to implement assembler directives such as .word, .quad,
+    /// etc.
+    ///
+    /// @param Value - The value to emit.
+    /// @param Size - The size of the integer (in bytes) to emit. This must
+    /// match a native machine width.
     virtual void EmitValue(const MCImm &Value, unsigned Size) = 0;
+
+    /// EmitInstruction - Emit the given @param Instruction into the current
+    /// section.
     virtual void EmitInstruction(const MCInst &Inst) = 0;
   };
 
+  /// createAsmStreamer - Create a machine code streamer which will print out
+  /// assembly for the native target, suitable for compiling with a native
+  /// assembler.
   MCStreamer *createAsmStreamer(MCContext &Ctx, raw_ostream &OS);
+
+  // FIXME: These two may end up getting rolled into a single
+  // createObjectStreamer interface, which implements the assembler backend, and
+  // is parameterized on an output object file writer.
+
+  /// createMachOStream - Create a machine code streamer which will generative
+  /// Mach-O format object files.
   MCStreamer *createMachOStreamer(MCContext &Ctx, raw_ostream &OS);
+
+  /// createELFStreamer - Create a machine code streamer which will generative
+  /// ELF format object files.
   MCStreamer *createELFStreamer(MCContext &Ctx, raw_ostream &OS);
 
 } // end namespace llvm