Document almost all modules

Fixes rust-lang#1082

Author: bjorn3

src/abi/comments.rs

@@ -1,3 +1,6 @@
+//! Annotate the clif ir with comments describing how arguments are passed into the current function
+//! and where all locals are stored.
+
 use std::borrow::Cow;
 
 use rustc_middle::mir;

src/abi/mod.rs

@@ -1,3 +1,5 @@
+//! Handling of everything related to the calling convention. Also fills `fx.local_map`.
+
 #[cfg(debug_assertions)]
 mod comments;
 mod pass_mode;
@@ -325,6 +327,7 @@ impl<'tcx, B: Backend + 'static> FunctionCx<'_, 'tcx, B> {
     }
 }
 
+/// Make a [`CPlace`] capable of holding value of the specified type.
 fn make_local_place<'tcx>(
     fx: &mut FunctionCx<'_, 'tcx, impl Backend>,
     local: Local,

src/abi/pass_mode.rs

@@ -1,3 +1,5 @@
+//! Argument passing
+
 use crate::prelude::*;
 
 pub(super) use EmptySinglePair::*;
@@ -118,6 +120,7 @@ pub(super) fn get_pass_mode<'tcx>(tcx: TyCtxt<'tcx>, layout: TyAndLayout<'tcx>)
     }
 }
 
+/// Get a set of values to be passed as function arguments.
 pub(super) fn adjust_arg_for_abi<'tcx>(
     fx: &mut FunctionCx<'_, 'tcx, impl Backend>,
     arg: CValue<'tcx>,
@@ -136,6 +139,8 @@ pub(super) fn adjust_arg_for_abi<'tcx>(
     }
 }
 
+/// Create a [`CValue`] containing the value of a function parameter adding clif function parameters
+/// as necessary.
 pub(super) fn cvalue_for_param<'tcx>(
     fx: &mut FunctionCx<'_, 'tcx, impl Backend>,
     start_block: Block,

src/abi/returning.rs

@@ -1,10 +1,13 @@
+//! Return value handling
+
 use crate::abi::pass_mode::*;
 use crate::prelude::*;
 
 fn return_layout<'a, 'tcx>(fx: &mut FunctionCx<'a, 'tcx, impl Backend>) -> TyAndLayout<'tcx> {
     fx.layout_of(fx.monomorphize(&fx.mir.local_decls[RETURN_PLACE].ty))
 }
 
+/// Can the given type be returned into an ssa var or does it need to be returned on the stack.
 pub(crate) fn can_return_to_ssa_var<'tcx>(
     tcx: TyCtxt<'tcx>,
     dest_layout: TyAndLayout<'tcx>,
@@ -16,6 +19,8 @@ pub(crate) fn can_return_to_ssa_var<'tcx>(
     }
 }
 
+/// Return a place where the return value of the current function can be written to. If necessary
+/// this adds an extra parameter pointing to where the return value needs to be stored.
 pub(super) fn codegen_return_param<'tcx>(
     fx: &mut FunctionCx<'_, 'tcx, impl Backend>,
     ssa_analyzed: &rustc_index::vec::IndexVec<Local, crate::analyze::SsaKind>,
@@ -59,6 +64,8 @@ pub(super) fn codegen_return_param<'tcx>(
     ret_place
 }
 
+/// Invokes the closure with if necessary a value representing the return pointer. When the closure
+/// returns the call return value(s) if any are written to the correct place.
 pub(super) fn codegen_with_call_return_arg<'tcx, B: Backend, T>(
     fx: &mut FunctionCx<'_, 'tcx, B>,
     fn_sig: FnSig<'tcx>,
@@ -102,6 +109,7 @@ pub(super) fn codegen_with_call_return_arg<'tcx, B: Backend, T>(
     (call_inst, meta)
 }
 
+/// Codegen a return instruction with the right return value(s) if any.
 pub(crate) fn codegen_return(fx: &mut FunctionCx<'_, '_, impl Backend>) {
     match get_pass_mode(fx.tcx, return_layout(fx)) {
         PassMode::NoPass | PassMode::ByRef { size: Some(_) } => {

src/allocator.rs

@@ -1,12 +1,5 @@
-// Copyright 2017 The Rust Project Developers. See the COPYRIGHT
-// file at the top-level directory of this distribution and at
-// http://rust-lang.org/COPYRIGHT.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
+//! Allocator shim
+// Adapted from rustc
 
 use crate::prelude::*;
 

src/analyze.rs

@@ -1,3 +1,5 @@
+//! SSA analysis
+
 use crate::prelude::*;
 
 use rustc_index::vec::IndexVec;

src/archive.rs

@@ -1,3 +1,5 @@
+//! Creation of ar archives like for the lib and staticlib crate type
+
 use std::collections::BTreeMap;
 use std::fs::File;
 use std::path::{Path, PathBuf};

src/backend.rs

@@ -1,3 +1,5 @@
+//! Abstraction around the object writing crate
+
 use std::convert::{TryFrom, TryInto};
 
 use rustc_data_structures::fx::FxHashMap;

src/base.rs

@@ -1,3 +1,5 @@
+//! Codegen of a single function
+
 use rustc_index::vec::IndexVec;
 use rustc_middle::ty::adjustment::PointerCast;
 

src/cast.rs

@@ -1,3 +1,5 @@
+//! Various number casting functions
+
 use crate::prelude::*;
 
 pub(crate) fn clif_intcast(

src/codegen_i128.rs

@@ -1,4 +1,4 @@
-//! Replaces 128-bit operators with lang item calls
+//! Replaces 128-bit operators with lang item calls where necessary
 
 use crate::prelude::*;
 

src/common.rs

@@ -302,7 +302,7 @@ pub(crate) struct FunctionCx<'clif, 'tcx, B: Backend + 'static> {
     /// When `#[track_caller]` is used, the implicit caller location is stored in this variable.
     pub(crate) caller_location: Option<CValue<'tcx>>,
 
-    /// See [crate::optimize::code_layout] for more information.
+    /// See [`crate::optimize::code_layout`] for more information.
     pub(crate) cold_blocks: EntitySet<Block>,
 
     pub(crate) clif_comments: crate::pretty_clif::CommentWriter,

src/constant.rs

@@ -1,3 +1,5 @@
+//! Handling of `static`s, `const`s and promoted allocations
+
 use rustc_span::DUMMY_SP;
 
 use rustc_data_structures::fx::FxHashSet;

src/debuginfo/emit.rs

@@ -1,3 +1,5 @@
+//! Write the debuginfo into an object file.
+
 use rustc_data_structures::fx::FxHashMap;
 
 use gimli::write::{Address, AttributeValue, EndianVec, Result, Sections, Writer};
@@ -55,6 +57,7 @@ pub(crate) enum DebugRelocName {
     Symbol(usize),
 }
 
+/// A [`Writer`] that collects all necessary relocations.
 #[derive(Clone)]
 pub(super) struct WriterRelocate {
     pub(super) relocs: Vec<DebugReloc>,
@@ -69,6 +72,7 @@ impl WriterRelocate {
         }
     }
 
+    /// Perform the collected relocations to be usable for JIT usage.
     #[cfg(feature = "jit")]
     pub(super) fn relocate_for_jit(
         mut self,

src/debuginfo/line_info.rs

@@ -1,3 +1,5 @@
+//! Line info generation (`.debug_line`)
+
 use std::ffi::OsStr;
 use std::path::{Component, Path};
 

src/debuginfo/mod.rs

@@ -1,3 +1,5 @@
+//! Handling of everything related to debuginfo.
+
 mod emit;
 mod line_info;
 mod unwind;

src/debuginfo/unwind.rs

@@ -1,3 +1,5 @@
+//! Unwind info generation (`.eh_frame`)
+
 use crate::prelude::*;
 
 use cranelift_codegen::isa::{unwind::UnwindInfo, TargetIsa};

src/discriminant.rs

@@ -1,3 +1,5 @@
+//! Handling of enum discriminants
+//!
 //! Adapted from https://github.com/rust-lang/rust/blob/d760df5aea483aae041c9a241e7acacf48f75035/src/librustc_codegen_ssa/mir/place.rs
 
 use rustc_target::abi::{Int, TagEncoding, Variants};

src/driver/aot.rs

@@ -1,3 +1,6 @@
+//! The AOT driver uses [`cranelift_object`] to write object files suitable for linking into a
+//! standalone executable.
+
 use std::path::PathBuf;
 
 use rustc_codegen_ssa::back::linker::LinkerInfo;

src/driver/jit.rs

@@ -1,3 +1,6 @@
+//! The JIT driver uses [`cranelift_simplejit`] to JIT execute programs without writing any object
+//! files.
+
 use std::ffi::CString;
 use std::os::raw::{c_char, c_int};
 

src/driver/mod.rs

@@ -1,3 +1,6 @@
+//! Drivers are responsible for calling [`codegen_mono_items`] and performing any further actions
+//! like JIT executing or writing object files.
+
 use std::any::Any;
 
 use rustc_middle::middle::cstore::EncodedMetadata;

src/inline_asm.rs

@@ -1,3 +1,5 @@
+//! Codegen of [`asm!`] invocations.
+
 use crate::prelude::*;
 
 use std::fmt::Write;

src/intrinsics/cpuid.rs

@@ -1,6 +1,8 @@
+//! Emulation of a subset of the cpuid x86 instruction.
+
 use crate::prelude::*;
 
-/// Emulates a subset of the cpuid call.
+/// Emulates a subset of the cpuid x86 instruction.
 ///
 /// This emulates an intel cpu with sse and sse2 support, but which doesn't support anything else.
 pub(crate) fn codegen_cpuid_call<'tcx>(

src/intrinsics/llvm.rs

@@ -1,3 +1,5 @@
+//! Emulate LLVM intrinsics
+
 use crate::intrinsics::*;
 use crate::prelude::*;
 

src/intrinsics/mod.rs

@@ -1,3 +1,6 @@
+//! Codegen of intrinsics. This includes `extern "rust-intrinsic"`, `extern "platform-intrinsic"`
+//! and LLVM intrinsics that have symbol names starting with `llvm.`.
+
 mod cpuid;
 mod llvm;
 mod simd;

src/intrinsics/simd.rs

@@ -1,3 +1,5 @@
+//! Codegen `extern "platform-intrinsic"` intrinsics.
+
 use super::*;
 use crate::prelude::*;
 

src/metadata.rs

@@ -1,3 +1,5 @@
+//! Reading and writing of the rustc metadata for rlibs and dylibs
+
 use std::convert::TryFrom;
 use std::fs::File;
 use std::path::Path;

src/num.rs

@@ -1,3 +1,5 @@
+//! Various operations on integer and floating-point numbers
+
 use crate::prelude::*;
 
 pub(crate) fn bin_op_to_intcc(bin_op: BinOp, signed: bool) -> Option<IntCC> {

src/optimize/mod.rs

@@ -1,3 +1,5 @@
+//! Various optimizations specific to cg_clif
+
 use crate::prelude::*;
 
 mod code_layout;

src/pointer.rs

@@ -1,9 +1,13 @@
+//! Defines [`Pointer`] which is used to improve the quality of the generated clif ir for pointer
+//! operations.
+
 use crate::prelude::*;
 
 use rustc_target::abi::Align;
 
 use cranelift_codegen::ir::immediates::Offset32;
 
+/// A pointer pointing either to a certain address, a certain stack slot or nothing.
 #[derive(Copy, Clone, Debug)]
 pub(crate) struct Pointer {
     base: PointerBase,