TAMER: Additional crate::ld documentation

tamer/src/ld.rs

@@ -15,18 +15,29 @@
 //  You should have received a copy of the GNU General Public License
 //  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-//! The [linker][] is responsible for combining individually compiled
-//!   [object files][] into a final executable.
+//! Combine [object files](crate::obj) into a final executable.
 //!
-//! It's user-facing binary is [`tameld`][tameld].
+//! It's user-facing binary is [`tameld`](../../tameld).
 //!
-//! **TODO:** More information.
+//!
+//! Background Information
+//! ======================
+//! A [linker][] is responsible for combining individually compiled
+//!   [object files](crate::obj) containing relocatable code into a final
+//!   executable.
+//! This involves putting the compiled code fragments into the right order
+//!   and into the right place within the executable.
 //!
 //! [linker]: https://en.wikipedia.org/wiki/Linker_(computing)
-//! [object files]: https://en.wikipedia.org/wiki/Object_file
-//! [tameld]: ../../tameld
 //!
-//! Backwards-Compatibility (XSLT System)
+//! _See below for more information on why this linker currently produces
+//!   another intermediate format (`xmle`) rather than a final executable._
+//!
+//! The type of relocatable code depends on the _target_.
+//! Currently, the only target is JavaScript.
+//!
+//!
+//! Backwards-Compatibility With XSLT System
 //! -------------------------------------
 //! This linker is part of the TAMER (TAME in Rust) project,
 //!   which aims to incrementally rewrite TAME in Rust.
@@ -44,5 +55,56 @@
 //!   the `xmle` file is still needed for other purposes,
 //!     such as `summary` and `dote` generation.
 //! Those too will eventually be linker targets.
+//!
+//!
+//! Linking Process
+//! ===============
+//! The linker works in the following steps:
+//!
+//!   1. [Object files](crate::obj) are recursively read.
+//!      They are used in a streaming manner for the next step of the
+//!        process;
+//!          they do not persist in memory.
+//!      Only the required portions of the file are loaded.
+//!      See the [Legacy IR](crate::ir::legacyir) for more information.
+//!
+//!   2. This information is used to populate the [ASG].
+//!      Information is added to the graph as it is discovered during object
+//!        file loading,
+//!          so the graph initially contains edges to missing identifiers.
+//!      Expressions are _not_ added to the graph,
+//!        as they are not needed for linking.
+//!      Once all data are loaded,
+//!        the ASG contains relocatable code fragments for each identifier.
+//!
+//!   3. The ASG is [sorted topologically][topo-sort] so that dependencies
+//!        will be written to the executable file before identifiers that
+//!        depend on them.
+//!      Roots for the sort are specified by the return map.
+//!      _Identifiers that are not accessable from one of those roots will be
+//!        omitted from the executable output._
+//!
+//!   4. Relocatable code fragments are output into various sections in the
+//!        executable file.
+//!      This output file is currently `xmle`.
+//!      (**TODO**: Link to new `xmle` crate.)
+//!
+//! [ASG]: crate::ir::asg
+//! [topo-sort]: https://en.wikipedia.org/wiki/Topological_sorting
+//!
+//! Steps 1 and 2 are performed at the same time:
+//!   object files are used to immediately populate the [ASG][].
+//! Since the ASG contains only partial information,
+//!   it must perform other validations (such as extern resolution) during
+//!   this process;
+//!     see [crate::ir::asg] for more information.
+//!
+//! Because the topological sort only considered explicitly defined roots,
+//!   identifiers are only included in the final executable if they are
+//!   either a root or are a dependency of a root.
+//! This makes it possible to create large reusable packages without
+//!   incurring a runtime cost for unused objects,
+//!     which is especially important since templates may expand into many
+//!     identifiers.
 
 pub mod poc;