message: document the implementation module
diff: @@ -2,6 +2,15 @@ use crate::class_table;
  use crate::compiler::{CompilerQueryContext, Interner};
  use salsa::query_context_storage;
  +/// Our "query context" is the context type that we will be threading
  +/// through our application (though 99% of the application only
  +/// interacts with it through traits and never knows its real name).
  +///
  +/// Query contexts can contain whatever you want them to, but salsa
  +/// requires two things:
  +///
  +/// - a salsa runtime (the `runtime` field, here)
  +/// - query storage (declared using the `query_context_storage` macro below)
  #[derive(Default)]
  pub struct QueryContextImpl {
  runtime: salsa::Runtime<QueryContextImpl>,
  @@ -9,8 +18,23 @@ pub struct QueryContextImpl {
  interner: Interner,
  }
  -// This is an example of how you "link up" all the queries in your
  -// application.
  +/// This impl tells salsa where to find the runtime and storage in
  +/// your query context.
  +impl salsa::QueryContext for QueryContextImpl {
  + fn salsa_storage(&self) -> &QueryContextImplStorage {
  + &self.storage
  + }
  +
  + fn salsa_runtime(&self) -> &salsa::runtime::Runtime<QueryContextImpl> {
  + &self.runtime
  + }
  +}
  +
  +/// Declares the "query storage" for your context. Here, you list out
  +/// all of the query traits from your application that you wish to
  +/// provide storage for. This macro will generate the appropriate
  +/// storage and also generate impls for those traits, so that you
  +/// `QueryContextImpl` type implements them.
  query_context_storage! {
  pub struct QueryContextImplStorage for QueryContextImpl {
  impl class_table::ClassTableQueryContext {
  @@ -21,27 +45,11 @@ query_context_storage! {
  }
  }
  -// This is an example of how you provide custom bits of stuff that
  -// your queries may need; in this case, an `Interner` value.
  +/// In addition to the "query provider" traits, you may have other
  +/// trait requirements that your application needs -- you can
  +/// implement those yourself (in this case, an `interner`).
  impl CompilerQueryContext for QueryContextImpl {
  fn interner(&self) -> &Interner {
  &self.interner
  }
  }
  -
  -// FIXME: This code... probably should not live here. But maybe we
  -// just want to provide some helpers or something? I do suspect I want
  -// people to be able to customize this.
  -//
  -// Seems like a classic case where specialization could be useful to
  -// permit behavior refinement.
  -
  -impl salsa::QueryContext for QueryContextImpl {
  - fn salsa_storage(&self) -> &QueryContextImplStorage {
  - &self.storage
  - }
  -
  - fn salsa_runtime(&self) -> &salsa::runtime::Runtime<QueryContextImpl> {
  - &self.runtime
  - }
  -}
  