newtype in types, more generator config, parsing -> parser

12 files changed, 256 insertions, 120 deletions

diff --git a/src/cli.rs b/src/cli.rs
index ff25792..0000644 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -21,11 +21,14 @@ pub(crate) struct Cli {
 
 #[derive(Debug, Clone, StructOpt)]
 pub(crate) enum Command {
-    Generate { file: String },
+    Generate {
+        file: String,
+    },
+    Inspect,
     Config {
         #[structopt(subcommand)]
         command: ConfigCommand,
-    }
+    },
 }
 
 #[derive(Debug, Clone, StructOpt)]
diff --git a/src/config.rs b/src/config.rs
index 72a9ff6..942dfcf 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -2,7 +2,7 @@ use crate::cli::Cli;
 use crate::generator::config::{
     Config as GeneratorConfig, ProvidedConfig as ProvidedGeneratorConfig,
 };
-use crate::parsing::clang::config::{Config as ClangConfig, ProvidedConfig as ProvidedClangConfig};
+use crate::parser::clang::config::{Config as ClangConfig, ProvidedConfig as ProvidedClangConfig};
 
 use anyhow::{anyhow, Context, Result};
 use codemap::CodeMap;
@@ -19,8 +19,8 @@ pub(super) const DEFAULT_PROJECT_CONFIGURATION_FILE_NAME: &str = "poseidoc.toml"
 #[derive(Debug, Clone, Serialize)]
 pub(crate) struct Config {
     pub(crate) name: String,
-    pub(crate) clang: ClangConfig,
     pub(crate) generator: GeneratorConfig,
+    pub(crate) clang: ClangConfig,
 }
 
 impl Default for Config {
@@ -57,7 +57,7 @@ pub(crate) struct ProvidedConfig {
     #[structopt(flatten)]
     #[serde(default)]
     pub(crate) clang: ProvidedClangConfig,
-    #[structopt(skip)]
+    #[structopt(flatten)]
     #[serde(default)]
     pub(crate) generator: ProvidedGeneratorConfig,
 }
diff --git a/src/generator/config.rs b/src/generator/config.rs
index 43fee60..3057fee 100644
--- a/src/generator/config.rs
+++ b/src/generator/config.rs
@@ -1,40 +1,58 @@
+use crate::types::*;
+
 use serde_derive::{Deserialize, Serialize};
 use structopt::StructOpt;
 
 use std::collections::{HashMap, HashSet};
 
+pub(crate) type Inlines = HashMap<Language, HashMap<EntityKind, HashSet<ChildrenKind>>>;
+
 #[derive(Debug, Clone, Serialize)]
 pub(crate) struct Config {
+    pub(super) from: String,
+    pub(super) to: String,
+    pub(super) pandoc_filters: Vec<String>,
     /// Tells us in which language, which entity types should inline which children entity type in
     /// their documentation.
     ///
     /// e.g. in C++, classes should inline their children methods documentation.
-    pub(crate) inlines: HashMap<String, HashMap<String, HashSet<String>>>,
+    pub(super) inlines: Inlines,
 }
 
 impl Config {
-    pub(crate) fn from_merge(_cli: ProvidedConfig, conf: ProvidedConfig) -> Self {
+    pub(crate) fn from_merge(mut cli: ProvidedConfig, mut conf: ProvidedConfig) -> Self {
+        conf.pandoc_filters.append(&mut cli.pandoc_filters);
         Self {
+            from: cli
+                .from
+                .or(conf.from)
+                .unwrap_or_else(|| String::from("markdown-raw_tex")),
+            to: cli.to.or(conf.to).unwrap_or_else(|| String::from("html")),
+            pandoc_filters: conf.pandoc_filters,
             inlines: conf.inlines.unwrap_or_else(default_inlines),
         }
     }
 }
 
-fn default_inlines() -> HashMap<String, HashMap<String, HashSet<String>>> {
+fn default_inlines() -> Inlines {
     let mut clang = HashMap::new();
     let mut clang_inline_children = HashSet::new();
-    // TODO: this is not great: no differences between variable/field for children, but differences
-    // as a parent...
-    clang_inline_children.insert(String::from("variable"));
-    //classes.insert(String::from("field"));
-    clang_inline_children.insert(String::from("function"));
-    //classes.insert(String::from("method"));
-    clang.insert(String::from("struct"), clang_inline_children.clone());
-    clang.insert(String::from("class"), clang_inline_children.clone());
-    clang.insert(String::from("namespace"), clang_inline_children);
+    clang_inline_children.insert(ChildrenKind(String::from("variables")));
+    clang_inline_children.insert(ChildrenKind(String::from("fields")));
+    clang_inline_children.insert(ChildrenKind(String::from("functions")));
+    clang_inline_children.insert(ChildrenKind(String::from("methods")));
+    clang.insert(
+        EntityKind(String::from("struct")),
+        clang_inline_children.clone(),
+    );
+    clang.insert(
+        EntityKind(String::from("class")),
+        clang_inline_children.clone(),
+    );
+    clang.insert(EntityKind(String::from("namespace")), clang_inline_children);
 
     let mut inlines = HashMap::new();
-    inlines.insert(String::from("clang"), clang);
+    inlines.insert(Language::Clang, clang);
 
     inlines
 }
@@ -48,6 +66,12 @@ impl Default for Config {
 #[derive(Debug, Clone, Default, StructOpt, Deserialize, Serialize)]
 #[serde(rename_all = "kebab-case")]
 pub(crate) struct ProvidedConfig {
+    #[structopt(long = "generator-from")]
+    pub(super) from: Option<String>,
+    #[structopt(long = "generator-to")]
+    pub(super) to: Option<String>,
+    #[structopt(long = "generator-pandoc-filters", number_of_values = 1)]
+    pub(super) pandoc_filters: Vec<String>,
     #[structopt(skip)]
-    pub(crate) inlines: Option<HashMap<String, HashMap<String, HashSet<String>>>>,
+    pub(super) inlines: Option<Inlines>,
 }
diff --git a/src/generator/mod.rs b/src/generator/mod.rs
index b4e1c94..3f62779 100644
--- a/src/generator/mod.rs
+++ b/src/generator/mod.rs
@@ -2,11 +2,8 @@ pub(crate) mod config;
 mod pandoc;
 
 use self::config::Config;
-//use crate::entities::{
-//    Description, DynEntity, EntitiesManager, EntitiesManagerComponents, Usr,
-//};
 use self::pandoc::into_pandoc;
-use crate::types::Entity;
+use crate::types::*;
 
 use anyhow::{ensure, Context, Result};
 use rayon::Scope;
@@ -18,7 +15,11 @@ use std::path::Path;
 
 const DEFAULT_CSS: &[u8] = include_bytes!("../../res/style.css");
 
-pub(crate) fn generate(base_dir: &Path, entities: BTreeMap<String, Entity>, config: &Config) -> Result<()> {
+pub(crate) fn generate(
+    base_dir: &Path,
+    entities: BTreeMap<EntityId, Entity>,
+    config: &Config,
+) -> Result<()> {
     let md_output_dir = base_dir.join("markdown");
     let html_output_dir = base_dir.join("html");
 
@@ -54,7 +55,7 @@ pub(crate) fn generate(base_dir: &Path, entities: BTreeMap<String, Entity>, conf
 }
 
 fn generate_recursively<'a>(
-    id: String,
+    id: EntityId,
     entity: Entity,
     pool: &Scope<'a>,
     md_output_dir: &'a Path,
@@ -63,7 +64,7 @@ fn generate_recursively<'a>(
     config: &'a Config,
 ) {
     pool.spawn(move |pool| {
-        trace!("Trying to generate {}", id);
+        trace!("Trying to generate {}", id.0);
 
         let leftovers = generate_single(
             &id,
@@ -90,18 +91,18 @@ fn generate_recursively<'a>(
 }
 
 fn generate_single(
-    id: &str,
+    id: &EntityId,
     entity: Entity,
     md_output_dir: impl AsRef<Path>,
     html_output_dir: impl AsRef<Path>,
     css_path: impl AsRef<Path>,
-    config: &Config
-) -> Result<BTreeMap<String, Entity>> {
+    config: &Config,
+) -> Result<BTreeMap<EntityId, Entity>> {
     use std::io::prelude::*;
     use std::process::{Command, Stdio};
 
-    let md_output_file = md_output_dir.as_ref().join(id);
-    let html_output_file = html_output_dir.as_ref().join(id);
+    let md_output_file = md_output_dir.as_ref().join(&id.0);
+    let html_output_file = html_output_dir.as_ref().join(&id.0);
 
     let mut command = Command::new("pandoc");
 
@@ -111,7 +112,10 @@ fn generate_single(
         .stderr(Stdio::piped())
         .args(&[
             "--from=json",
-            "--to=markdown",
+            // standalone keeps the sent metadat
+            "--standalone",
+            "--to",
+            &config.from,
             "--output",
             md_output_file
                 .to_str()
@@ -165,8 +169,10 @@ fn generate_single(
         .stdout(Stdio::piped())
         .stderr(Stdio::piped())
         .args(&[
-            "--from=markdown-raw_tex",
-            "--to=html",
+            "--from",
+            &config.from,
+            "--to",
+            &config.to,
             "--css",
             css_path
                 .as_ref()
@@ -183,6 +189,10 @@ fn generate_single(
                 .context("Entity name is not valid UTF-8")?,
         ]);
 
+    for filter in &config.pandoc_filters {
+        command.args(&["--filter", filter]);
+    }
+
     let command_str = format!("{:?}", command);
     debug!("Launching command: {}", command_str);
 
@@ -190,6 +200,8 @@ fn generate_single(
         .output()
         .context("Failed to execute Pandoc command")?;
 
+    std::io::stderr().lock().write_all(&output.stderr)?;
+
     ensure!(
         output.status.success(),
         CommandError {
diff --git a/src/generator/pandoc.rs b/src/generator/pandoc.rs
index 1753d34..035acab 100644
--- a/src/generator/pandoc.rs
+++ b/src/generator/pandoc.rs
@@ -1,14 +1,11 @@
 use super::config::Config;
-use crate::types::Entity;
+use crate::types::*;
 
 use pandoc_types::definition::{Attr, Block, Inline, Meta, MetaValue, Pandoc};
 
 use std::collections::BTreeMap;
 
-pub(crate) fn into_pandoc(
-    entity: Entity,
-    config: &Config,
-) -> (Pandoc, BTreeMap<String, Entity>) {
+pub(crate) fn into_pandoc(entity: Entity, config: &Config) -> (Pandoc, BTreeMap<EntityId, Entity>) {
     let mut meta = Meta::null();
 
     let title = vec![Inline::Code(Attr::null(), entity.name.clone())];
@@ -57,7 +54,7 @@ pub(crate) fn into_pandoc(
             content.push(Block::Header(
                 2,
                 Attr::null(),
-                vec![Inline::Str(String::from(section_name))],
+                vec![Inline::Str(section_name.0.clone())],
             ));
 
             content.push(members_list);
@@ -71,7 +68,7 @@ pub(crate) fn into_pandoc(
             content.push(Block::Header(
                 2,
                 Attr::null(),
-                vec![Inline::Str(section_name.clone())],
+                vec![Inline::Str(section_name.0.clone())],
             ));
 
             content.push(members_list);
@@ -79,7 +76,7 @@ pub(crate) fn into_pandoc(
             embedded_documentation.push(Block::Header(
                 2,
                 Attr::null(),
-                vec![Inline::Str(section_name + " Documentation")],
+                vec![Inline::Str(section_name.0 + " Documentation")],
             ));
 
             for (_id, child) in children {
@@ -112,7 +109,7 @@ fn str_block(content: String) -> Block {
     Block::Plain(vec![Inline::Str(content)])
 }
 
-fn entity_link(id: &str, name: String) -> Inline {
+fn entity_link(id: &EntityId, name: String) -> Inline {
     use pandoc_types::definition::Target;
     use percent_encoding::{utf8_percent_encode, AsciiSet, CONTROLS};
 
@@ -135,7 +132,7 @@ fn entity_link(id: &str, name: String) -> Inline {
         vec![Inline::Code(Attr::null(), name)],
         Target(
             once("./")
-                .chain(utf8_percent_encode(id, FRAGMENT))
+                .chain(utf8_percent_encode(&id.0, FRAGMENT))
                 .collect(),
             String::new(),
         ),
@@ -147,7 +144,7 @@ fn raw_markdown(text: String) -> Block {
     Block::RawBlock(Format(String::from("markdown")), text)
 }
 
-fn member_list<'a>(members: impl IntoIterator<Item = (&'a String, &'a Entity)>) -> Option<Block> {
+fn member_list<'a>(members: impl IntoIterator<Item = (&'a EntityId, &'a Entity)>) -> Option<Block> {
     let definitions: Vec<(Vec<Inline>, Vec<Vec<Block>>)> = members
         .into_iter()
         .map(|(id, entity)| {
diff --git a/src/main.rs b/src/main.rs
index b42d73c..5c613e0 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -3,7 +3,7 @@
 mod cli;
 mod config;
 mod generator;
-mod parsing;
+mod parser;
 mod types;
 
 #[macro_use]
@@ -87,12 +87,17 @@ fn start(codemap: &mut CodeMap) -> Result<()> {
             //let file = file.clone();
             let config = load_effective_config(cli, codemap)?;
 
-            let entities = parsing::clang::parse_compile_commands(&config.clang, codemap)?;
+            let entities = parser::clang::parse_compile_commands(&config.clang, codemap)?;
             //let manager = parse_file(file, &config.extra_clang_args);
 
             let base_output_dir = std::path::Path::new("doc");
             generate(&base_output_dir, entities, &config.generator)?;
         }
+        Command::Inspect => {
+            let config = load_effective_config(cli, codemap)?;
+            let entities = parser::clang::parse_compile_commands(&config.clang, codemap)?;
+            serde_json::to_writer_pretty(std::io::stdout().lock(), &entities)?;
+        }
         Command::Config {
             command: ConfigCommand::Default,
         } => {
diff --git a/src/parsing/clang/config.rs b/src/parser/clang/config.rs
index cb05876..05fe3ab 100644
--- a/src/parsing/clang/config.rs
+++ b/src/parser/clang/config.rs
@@ -7,18 +7,18 @@ use std::path::PathBuf;
 #[derive(Debug, Clone, StructOpt, Deserialize, Serialize)]
 #[serde(rename_all = "kebab-case")]
 pub(crate) struct Config {
-    pub(crate) compile_commands_location: PathBuf,
-    pub(crate) extra_args: Vec<String>,
+    pub(super) compile_commands_location: PathBuf,
+    pub(super) extra_args: Vec<String>,
 }
 
 #[derive(Debug, Clone, Default, StructOpt, Deserialize, Serialize)]
 #[serde(rename_all = "kebab-case")]
 pub(crate) struct ProvidedConfig {
     #[structopt(long = "clang-compile-commands-location")]
-    pub(crate) compile_commands_location: Option<PathBuf>,
+    pub(super) compile_commands_location: Option<PathBuf>,
     #[structopt(long = "clang-extra-args", number_of_values = 1)]
     #[serde(default)]
-    pub(crate) extra_args: Vec<String>,
+    pub(super) extra_args: Vec<String>,
 }
 
 impl Default for Config {
diff --git a/src/parsing/clang/entities.rs b/src/parser/clang/entities.rs
index a8062bb..41fe061 100644
--- a/src/parsing/clang/entities.rs
+++ b/src/parser/clang/entities.rs
@@ -1,4 +1,4 @@
-use crate::types::Entity;
+use crate::types::*;
 
 use clang::{EntityKind, Usr};
 use thiserror::Error;
@@ -16,7 +16,7 @@ pub(super) struct Children {
     functions: Option<BTreeMap<Usr, Described<Function>>>,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(super) enum ClangEntityKind {
     Namespace,
     Variable(VariableKind),
@@ -24,24 +24,50 @@ pub(super) enum ClangEntityKind {
     Function(FunctionKind),
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(super) enum VariableKind {
     Variable,
     Field,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(super) enum StructKind {
     Struct,
     Class,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(super) enum FunctionKind {
     Function,
     Method,
 }
 
+impl ClangEntityKind {
+    fn to_str_singular(self) -> &'static str {
+        match self {
+            ClangEntityKind::Namespace => "namespace",
+            ClangEntityKind::Variable(VariableKind::Variable) => "variable",
+            ClangEntityKind::Variable(VariableKind::Field) => "field",
+            ClangEntityKind::Struct(StructKind::Struct) => "struct",
+            ClangEntityKind::Struct(StructKind::Class) => "class",
+            ClangEntityKind::Function(FunctionKind::Function) => "function",
+            ClangEntityKind::Function(FunctionKind::Method) => "method",
+        }
+    }
+
+    fn to_str_plural(self) -> &'static str {
+        match self {
+            ClangEntityKind::Namespace => "namespaces",
+            ClangEntityKind::Variable(VariableKind::Variable) => "variables",
+            ClangEntityKind::Variable(VariableKind::Field) => "fields",
+            ClangEntityKind::Struct(StructKind::Struct) => "structs",
+            ClangEntityKind::Struct(StructKind::Class) => "classes",
+            ClangEntityKind::Function(FunctionKind::Function) => "functions",
+            ClangEntityKind::Function(FunctionKind::Method) => "methods",
+        }
+    }
+}
+
 #[derive(Debug, Error)]
 #[error("Unsupported Clang entity kind: {:?}", _0)]
 pub(super) struct TryFromEntityKindError(String);
@@ -66,7 +92,7 @@ impl TryFrom<EntityKind> for ClangEntityKind {
 }
 
 pub(super) trait ClangEntity {
-    fn kind(&self) -> &'static str;
+    fn kind(&self) -> ClangEntityKind;
 
     fn get_member_namespaces(&mut self) -> Option<&mut BTreeMap<Usr, Described<Namespace>>> {
         None
@@ -145,54 +171,58 @@ where
 
 impl<T: ClangEntity> From<Described<T>> for Entity {
     fn from(entity: Described<T>) -> Self {
-        let mut children = BTreeMap::new();
+        let mut children: BTreeMap<ChildrenKind, BTreeMap<EntityId, Entity>> = BTreeMap::new();
 
-        let kind = String::from(entity.entity.kind());
+        let kind = EntityKind(String::from(entity.entity.kind().to_str_singular()));
         let clang_children = entity.entity.into_children();
 
         if let Some(namespaces) = clang_children.namespaces {
-            children.insert(
-                String::from("namespace"),
-                namespaces
-                    .into_iter()
-                    .map(|(usr, namespace)| (usr.0, namespace.into()))
-                    .collect(),
-            );
+            for (usr, namespace) in namespaces {
+                children
+                    .entry(ChildrenKind(String::from(
+                        namespace.entity.kind().to_str_plural(),
+                    )))
+                    .or_default()
+                    .insert(EntityId(usr.0), namespace.into());
+            }
         }
 
         if let Some(variables) = clang_children.variables {
-            children.insert(
-                String::from("variable"),
-                variables
-                    .into_iter()
-                    .map(|(usr, variable)| (usr.0, variable.into()))
-                    .collect(),
-            );
+            for (usr, variable) in variables {
+                children
+                    .entry(ChildrenKind(String::from(
+                        variable.entity.kind().to_str_plural(),
+                    )))
+                    .or_default()
+                    .insert(EntityId(usr.0), variable.into());
+            }
         }
 
         if let Some(structs) = clang_children.structs {
-            children.insert(
-                String::from("struct"),
-                structs
-                    .into_iter()
-                    .map(|(usr, the_struct)| (usr.0, the_struct.into()))
-                    .collect(),
-            );
+            for (usr, r#struct) in structs {
+                children
+                    .entry(ChildrenKind(String::from(
+                        r#struct.entity.kind().to_str_plural(),
+                    )))
+                    .or_default()
+                    .insert(EntityId(usr.0), r#struct.into());
+            }
         }
 
         if let Some(functions) = clang_children.functions {
-            children.insert(
-                String::from("function"),
-                functions
-                    .into_iter()
-                    .map(|(usr, function)| (usr.0, function.into()))
-                    .collect(),
-            );
+            for (usr, function) in functions {
+                children
+                    .entry(ChildrenKind(String::from(
+                        function.entity.kind().to_str_plural(),
+                    )))
+                    .or_default()
+                    .insert(EntityId(usr.0), function.into());
+            }
         }
 
         Entity {
             name: entity.description.name,
-            language: String::from("clang"),
+            language: Language::Clang,
             kind,
             brief_description: entity.description.brief,
             documentation: entity.description.detailed,
@@ -223,8 +253,8 @@ pub(super) struct Namespace {
 }
 
 impl ClangEntity for Namespace {
-    fn kind(&self) -> &'static str {
-        "namespace"
+    fn kind(&self) -> ClangEntityKind {
+        ClangEntityKind::Namespace
     }
 
     fn get_member_namespaces(&mut self) -> Option<&mut BTreeMap<Usr, Described<Namespace>>> {
@@ -268,11 +298,8 @@ pub(super) struct Variable {
 }
 
 impl ClangEntity for Variable {
-    fn kind(&self) -> &'static str {
-        match self.kind {
-            VariableKind::Variable => "variable",
-            VariableKind::Field => "field",
-        }
+    fn kind(&self) -> ClangEntityKind {
+        ClangEntityKind::Variable(self.kind)
     }
 }
 
@@ -297,11 +324,8 @@ pub(super) struct Struct {
 }
 
 impl ClangEntity for Struct {
-    fn kind(&self) -> &'static str {
-        match self.kind {
-            StructKind::Struct => "struct",
-            StructKind::Class => "class",
-        }
+    fn kind(&self) -> ClangEntityKind {
+        ClangEntityKind::Struct(self.kind)
     }
 
     fn get_member_variables(&mut self) -> Option<&mut BTreeMap<Usr, Described<Variable>>> {
@@ -343,11 +367,8 @@ pub(super) struct Function {
 }
 
 impl ClangEntity for Function {
-    fn kind(&self) -> &'static str {
-        match self.kind {
-            FunctionKind::Function => "function",
-            FunctionKind::Method => "method",
-        }
+    fn kind(&self) -> ClangEntityKind {
+        ClangEntityKind::Function(self.kind)
     }
 }
 
diff --git a/src/parsing/clang/mod.rs b/src/parser/clang/mod.rs
index 047c49e..047c49e 100644
--- a/src/parsing/clang/mod.rs
+++ b/src/parser/clang/mod.rs
diff --git a/src/parsing/clang/parsing.rs b/src/parser/clang/parsing.rs
index 5359253..a654681 100644
--- a/src/parsing/clang/parsing.rs
+++ b/src/parser/clang/parsing.rs
@@ -1,6 +1,6 @@
 use super::config::Config;
 use super::entities::*;
-use crate::types::Entity;
+use crate::types::*;
 
 use anyhow::{anyhow, Context, Error, Result};
 use clang::{Clang, CompilationDatabase, Index, TranslationUnit, Usr};
@@ -208,7 +208,7 @@ impl FromTopLevel for Struct {
 pub(crate) fn parse_compile_commands(
     config: &Config,
     codemap: &mut CodeMap,
-) -> Result<BTreeMap<String, Entity>> {
+) -> Result<BTreeMap<EntityId, Entity>> {
     let clang = Clang::new().unwrap();
     let index = Index::new(
         &clang, /* exclude from pch = */ false, /* print diagnostics = */ false,
@@ -280,10 +280,25 @@ pub(crate) fn parse_compile_commands(
     let normalized_entities = entities
         .namespaces
         .into_iter()
-        .map(|(usr, entity)| (usr.0, entity.into()))
-        .chain(entities.variables.into_iter().map(|(usr, entity)| (usr.0, entity.into())))
-        .chain(entities.structs.into_iter().map(|(usr, entity)| (usr.0, entity.into())))
-        .chain(entities.functions.into_iter().map(|(usr, entity)| (usr.0, entity.into())))
+        .map(|(usr, entity)| (EntityId(usr.0), entity.into()))
+        .chain(
+            entities
+                .variables
+                .into_iter()
+                .map(|(usr, entity)| (EntityId(usr.0), entity.into())),
+        )
+        .chain(
+            entities
+                .structs
+                .into_iter()
+                .map(|(usr, entity)| (EntityId(usr.0), entity.into())),
+        )
+        .chain(
+            entities
+                .functions
+                .into_iter()
+                .map(|(usr, entity)| (EntityId(usr.0), entity.into())),
+        )
         .collect();
 
     Ok(normalized_entities)
@@ -463,11 +478,12 @@ fn add_entity(
     };
 
     if let Some(in_tree_entity) = toplevel.get_entity_mut(libclang_entity) {
-    // if current.has_documentation && !tree.has_documentation {
-    //     append_documentation
-    // }
+        // if current.has_documentation && !tree.has_documentation {
+        //     append_documentation
+        // }
     } else if libclang_entity.is_definition() {
         // TODO: This probably means that you can't put documentation in forward declarations.
+        // TODO: Ad-hoc toplevel functions are not documented
         //
         // This seems restrictive, but since there can be multiple declarations but only one definition,
         // you should probably put your documentation on the definition anyway?
diff --git a/src/parsing/mod.rs b/src/parser/mod.rs
index 0736eee..0736eee 100644
--- a/src/parsing/mod.rs
+++ b/src/parser/mod.rs
diff --git a/src/types.rs b/src/types.rs
index 82f9c65..f378f8b 100644
--- a/src/types.rs
+++ b/src/types.rs
@@ -1,22 +1,80 @@
 use serde_derive::{Serialize, Deserialize};
+use thiserror::Error;
 
 use std::collections::BTreeMap;
+use std::str::FromStr;
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct Poseidoc {
     pub config: toml::Value,
     pub entities: BTreeMap<String, Entity>,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Entity {
     pub name: String,
     //location: SourceLocation
-    pub language: String,
-    pub kind: String,
+    pub language: Language,
+    pub kind: EntityKind,
     pub brief_description: String,
     pub documentation: String,
-    pub children: BTreeMap<String, BTreeMap<String, Entity>>,
+    pub children: BTreeMap<ChildrenKind, BTreeMap<EntityId, Entity>>,
 }
 
-// TODO: use newtype for language, entity kind, entity ID
+// TODO: use newtype for entity kind, entity ID
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(try_from = "&str", into = "&'static str")]
+pub enum Language {
+    Clang,
+}
+
+impl std::fmt::Display for Language {
+    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+        write!(f, "{}", <&'static str>::from(*self))
+    }
+}
+
+impl FromStr for Language {
+    type Err = LanguageParseError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s {
+            "clang" => Ok(Language::Clang),
+            _ => Err(LanguageParseError(())),
+        }
+    }
+}
+
+impl std::convert::TryFrom<&str> for Language {
+    type Error = LanguageParseError;
+    fn try_from(s: &str) -> Result<Language, Self::Error> {
+        Language::from_str(s)
+    }
+}
+
+impl From<Language> for &'static str {
+    fn from(lang: Language) -> &'static str {
+        match lang {
+            Language::Clang => "clang",
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Error)]
+#[error("invalid language")]
+pub struct LanguageParseError(());
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct EntityKind(pub String);
+
+// Plural version of EntityKind
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct ChildrenKind(pub String);
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct EntityId(pub String);