Type linking/referencing

[kitsonk]

Ref #111

@lucacasonato and I had a conversation and I did some thinking on this particular problem. Currently the output does not resolve the symbol for a type reference, and leaves it up to the consumer to do. This can be complicated and error prone. The documentation should provide information to "link" to that symbol in the most effective way:

We modify the TsTypeRefDef to be the following:

pub enum Scope {
  Global,
  Namespace(String),
  Local,
}

pub struct TsTypeSymbol {
  pub scope: Scope,
  pub location: Option<Location>,
  pub name: String,
}

pub struct TsTypeRefDef {
  pub type_params: Option<Vec<TsTypeDef>>,
  pub type_name: String,
  pub symbol: Option<TsTypeSymbol>,
}

We have already integrated deno_graph into deno_doc so the ability to resolved imported symbols should be possible, but the ability to express the global scope is needed to be able to supply this. I also think that if the type ref can't be resolved with the supplied information, we would just get a None in the reference.

Things might need to change a bit when getting into the implementation, but I think with this information, downstream consumers of the data would be able to easily provide "links" when printing the doc nodes.

[lucacasonato]

How would this represent a nested namespace? Ie Deno.errors.Interrupted?

[kitsonk]

How would this represent a nested namespace? Ie Deno.errors.Interrupted?

Good point. I expected the Namespace to be fully qualified, and could be split by the consumer, but maybe splitting it should be part of it, so:

pub enum Scope {
  Global,
  Namespace(Vec<String>),
  Local,
}

So in the case you mentioned here:

let ref = TsTypeRefDef {
  type_params: None,
  type_name: "Interrupted".to_string(),
  symbol: Some(TsTypeSymbol {
    scope: Scope::Namespace(vec!["Deno".to_string(), "errors".to_string()]),
    location: None,
    name: "Interrupted".to_string(),
  }
};