Document more of the codegen features

libsolidity/codegen/Compiler.h

@@ -40,6 +40,8 @@ public:
 		m_context(&m_runtimeContext)
 	{ }
 
+	/// Compiles a contract.
+	/// @arg _metadata contains the to be injected metadata CBOR
 	void compileContract(
 		ContractDefinition const& _contract,
 		std::map<ContractDefinition const*, eth::Assembly const*> const& _contracts,
@@ -51,8 +53,11 @@ public:
 		ContractDefinition const& _contract,
 		std::map<ContractDefinition const*, eth::Assembly const*> const& _contracts
 	);
+	/// @returns Entire assembly.
 	eth::Assembly const& assembly() const { return m_context.assembly(); }
+	/// @returns The entire assembled object (with constructor).
 	eth::LinkerObject assembledObject() const { return m_context.assembledObject(); }
+	/// @returns Only the runtime object (without constructor).
 	eth::LinkerObject runtimeObject() const { return m_context.assembledRuntimeObject(m_runtimeSub); }
 	/// @arg _sourceCodes is the map of input files to source code strings
 	/// @arg _inJsonFromat shows whether the out should be in Json format

libsolidity/codegen/CompilerContext.h

@@ -56,7 +56,9 @@ public:
 			m_runtimeSub = size_t(m_asm->newSub(m_runtimeContext->m_asm).data());
 	}
 
+	/// Update currently enabled set of experimental features.
 	void setExperimentalFeatures(std::set<ExperimentalFeature> const& _features) { m_experimentalFeatures = _features; }
+	/// @returns true if the given feature is enabled.
 	bool experimentalFeatureActive(ExperimentalFeature _feature) const { return m_experimentalFeatures.count(_feature); }
 
 	void addStateVariable(VariableDeclaration const& _declaration, u256 const& _storageOffset, unsigned _byteOffset);
@@ -78,13 +80,15 @@ public:
 	/// @returns the entry label of the given function. Might return an AssemblyItem of type
 	/// UndefinedItem if it does not exist yet.
 	eth::AssemblyItem functionEntryLabelIfExists(Declaration const& _declaration) const;
-	void setInheritanceHierarchy(std::vector<ContractDefinition const*> const& _hierarchy) { m_inheritanceHierarchy = _hierarchy; }
 	/// @returns the entry label of the given function and takes overrides into account.
 	FunctionDefinition const& resolveVirtualFunction(FunctionDefinition const& _function);
 	/// @returns the function that overrides the given declaration from the most derived class just
 	/// above _base in the current inheritance hierarchy.
 	FunctionDefinition const& superFunction(FunctionDefinition const& _function, ContractDefinition const& _base);
+	/// @returns the next constructor in the inheritance hierarchy.
 	FunctionDefinition const* nextConstructor(ContractDefinition const& _contract) const;
+	/// Sets the current inheritance hierarchy from derived to base.
+	void setInheritanceHierarchy(std::vector<ContractDefinition const*> const& _hierarchy) { m_inheritanceHierarchy = _hierarchy; }
 
 	/// @returns the next function in the queue of functions that are still to be compiled
 	/// (i.e. that were referenced during compilation but where we did not yet generate code for).
@@ -155,6 +159,7 @@ public:
 	/// Adds a subroutine to the code (in the data section) and pushes its size (via a tag)
 	/// on the stack. @returns the pushsub assembly item.
 	eth::AssemblyItem addSubroutine(eth::AssemblyPointer const& _assembly) { return m_asm->appendSubroutine(_assembly); }
+	/// Pushes the size of the subroutine.
 	void pushSubroutineSize(size_t _subRoutine) { m_asm->pushSubroutineSize(_subRoutine); }
 	/// Pushes the offset of the subroutine.
 	void pushSubroutineOffset(size_t _subRoutine) { m_asm->pushSubroutineOffset(_subRoutine); }
@@ -189,6 +194,7 @@ public:
 	/// Appends arbitrary data to the end of the bytecode.
 	void appendAuxiliaryData(bytes const& _data) { m_asm->appendAuxiliaryDataToEnd(_data); }
 
+	/// Run optimisation step.
 	void optimise(bool _fullOptimsation, unsigned _runs = 200) { m_asm->optimise(_fullOptimsation, true, _runs); }
 
 	/// @returns the runtime context if in creation mode and runtime context is set, nullptr otherwise.
@@ -196,6 +202,7 @@ public:
 	/// @returns the identifier of the runtime subroutine.
 	size_t runtimeSub() const { return m_runtimeSub; }
 
+	/// @returns a const reference to the underlying assembly.
 	eth::Assembly const& assembly() const { return *m_asm; }
 	/// @returns non-const reference to the underlying assembly. Should be avoided in favour of
 	/// wrappers in this class.

libsolidity/codegen/CompilerUtils.h

@@ -38,14 +38,20 @@ public:
 	/// Stores the initial value of the free-memory-pointer at its position;
 	void initialiseFreeMemoryPointer();
 	/// Copies the free memory pointer to the stack.
+	/// Stack pre:
+	/// Stack post: <mem_start>
 	void fetchFreeMemoryPointer();
 	/// Stores the free memory pointer from the stack.
+	/// Stack pre: <mem_end>
+	/// Stack post:
 	void storeFreeMemoryPointer();
 	/// Allocates a number of bytes in memory as given on the stack.
 	/// Stack pre: <size>
 	/// Stack post: <mem_start>
 	void allocateMemory();
 	/// Appends code that transforms memptr to (memptr - free_memptr) memptr
+	/// Stack pre: <mem_end>
+	/// Stack post: <size> <mem_start>
 	void toSizeAfterFreeMemoryPointer();
 
 	/// Loads data from memory to the stack.
@@ -105,6 +111,8 @@ public:
 
 	/// Special case of @a encodeToMemory which assumes that everything is padded to words
 	/// and dynamic data is not copied in place (i.e. a proper ABI encoding).
+	/// Stack pre: <value0> <value1> ... <valueN-1> <head_start>
+	/// Stack post: <mem_ptr>
 	void abiEncode(
 		TypePointers const& _givenTypes,
 		TypePointers const& _targetTypes,
@@ -185,9 +193,13 @@ public:
 	static unsigned sizeOnStack(std::vector<std::shared_ptr<Type const>> const& _variableTypes);
 
 	/// Helper function to shift top value on the stack to the left.
+	/// Stack pre: <value> <shift_by_bits>
+	/// Stack post: <shifted_value>
 	void leftShiftNumberOnStack(unsigned _bits);
 
 	/// Helper function to shift top value on the stack to the right.
+	/// Stack pre: <value> <shift_by_bits>
+	/// Stack post: <shifted_value>
 	void rightShiftNumberOnStack(unsigned _bits, bool _isSigned = false);
 
 	/// Appends code that computes tha Keccak-256 hash of the topmost stack element of 32 byte type.