Feature/issue 109 docu (#122)

* feat: write some basic Rustdoc

* test rustdoc github action

* github action permission

* feat: move action into ide

* feat: add basic Comments and documentation to files

* some more fine tuning for the documentation

* fix: add automatic redirect to right github page

* fix github action

* feat: Docs cleanup

* feat: restrict github action condition

* feat: change docs link

Author: felixrieg

.github/workflows/rustdoc.yml

@@ -0,0 +1,40 @@
+name: rustdoc
+on:
+  pull_request:
+    branches: [ "master" ]
+
+
+env:
+  CARGO_INCREMENTAL: 0
+  CARGO_NET_RETRY: 10
+  RUSTFLAGS: "-D warnings -W unreachable-pub"
+  RUSTUP_MAX_RETRIES: 10
+
+jobs:
+  rustdoc:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    - name: Install Rust toolchain
+      run: rustup update --no-self-update stable
+
+    - name: Build Documentation
+      run: cargo doc --all --no-deps
+
+    - name: relink Github pages
+      # Add redirect to uvls doc site as main Page
+      run: echo '<meta http-equiv="refresh" content="0; url=./uvls" />' > ./target/doc/index.html
+
+    - name: Deploy Docs
+      uses: peaceiris/actions-gh-pages@364c31d33bb99327c77b3a5438a83a357a6729ad # v3.4.0
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_branch: gh-pages
+        publish_dir: ./target/doc
+        force_orphan: true

README.md

@@ -2,6 +2,9 @@
 [UVL](https://github.com/Universal-Variability-Language) language server based on [tree-sitter](https://github.com/tree-sitter/tree-sitter).
 
 ## Getting started
+
+### Docs
+Basic Documentation for the Codebase: [Docs](https://universal-variability-language.github.io/uvl-lsp/uvls/)
 ### Build
 - Requirements
     - Rust 1.65+
@@ -60,6 +63,3 @@ we can capture many incorrect expressions and provide decent error messages in m
 Tree-sitter queries allow for easy symbol extraction and are used to transform the tree-sitter tree into a more compact graph.
 This graph is then used for further analysis.
 Queries are also used for syntax highlighting as tree-sitter was originally intended for that.
-
-
-

uvls/src/core/ast.rs

@@ -1,3 +1,12 @@
+//! Easy to work with AST parsing and util.
+//!
+//! The AST is stored as an ECS like structure
+//! This allows fast queries over all features groups etc.
+//! Features, Attributes, Imports and Directories are stored in a typed radix tree.
+//! The radix tree is represented via a map (sym0,name,ty) -> sym1
+//! where ty is the type of sym1. Using this representation lowers total
+//! memory consumption by a nice 20%
+
 use crate::core::*;
 use check::ErrorInfo;
 use hashbrown::HashMap;
@@ -18,13 +27,7 @@ mod transform;
 mod visitor;
 pub use def::*;
 pub use visitor::*;
-//Easy to work with AST parsing and util.
-//The AST is stored as an ECS like structure
-//This allows fast queries over all features groups etc.
-//Features, Attributes, Imports and Directories are stored in a typed radix tree.
-//The radix tree is represented via a map (sym0,name,ty) -> sym1
-//where ty is the type of sym1. Using this representation lowers total
-//memory consumption by a nice 20%
+
 pub fn uri_to_path(uri: &Url) -> Option<Vec<Ustr>> {
     let mut p = uri.to_file_path().ok()?;
     p.set_extension("");
@@ -47,7 +50,7 @@ where
     }
 }
 
-//1->N parent child relation
+/// 1->N parent child relation
 #[derive(Default, Debug, Clone)]
 struct TreeMap {
     children: HashMap<Symbol, Vec<Symbol>>,
@@ -59,7 +62,7 @@ impl TreeMap {
         self.parent.insert(child, parent);
     }
 }
-//Ast container each symbol kind lives in its own vector
+/// Ast container each symbol kind lives in its own vector
 #[derive(Clone, Debug, Default)]
 struct Ast {
     keywords: Vec<Keyword>,
@@ -90,7 +93,7 @@ impl Ast {
             _ => unimplemented!(),
         }
     }
-    //call f for each child under sym and prefix
+    /// call f for each child under sym and prefix
     fn lookup<F: FnMut(Symbol)>(&self, sym: Symbol, prefix: Ustr, mut f: F) {
         match sym {
             Symbol::Root => {
@@ -143,7 +146,7 @@ impl Ast {
     fn lsp_range(&self, sym: Symbol, source: &Rope) -> Option<tower_lsp::lsp_types::Range> {
         self.span(sym).and_then(|s| lsp_range(s, source))
     }
-    //source range for a symbol if there is any
+    /// source range for a symbol if there is any
     fn span(&self, sym: Symbol) -> Option<Span> {
         match sym {
             Symbol::Feature(i) => Some(self.features[i].name.span.clone()),
@@ -171,7 +174,7 @@ impl Ast {
             .into_iter()
             .flat_map(|v| v.iter().cloned())
     }
-    //utility iterators over different elements of interest
+    /// utility iterators over different elements of interest
     fn all_imports(&self) -> impl Iterator<Item = Symbol> + DoubleEndedIterator {
         (0..self.import.len()).map(Symbol::Import)
     }
@@ -217,7 +220,7 @@ impl Ast {
     fn all_lang_lvls(&self) -> impl Iterator<Item = Symbol> {
         (0..self.includes.len()).map(Symbol::LangLvl)
     }
-    //Search a symbol by byte offset in O(N)
+    /// Search a symbol by byte offset in O(N)
     fn find(&self, offset: usize) -> Option<Symbol> {
         self.all_imports()
             .chain(self.all_features())
@@ -250,7 +253,7 @@ impl Ast {
         return relatives;
     }
 }
-//Combines the AST with metadata, this is also a public interface to the AST.
+/// Combines the AST with metadata, this is also a public interface to the AST.
 #[derive(Clone, Debug)]
 pub struct AstDocument {
     ast: Ast,
@@ -270,7 +273,7 @@ impl AstDocument {
             self.ast.structure.parent.get(&sym).cloned()
         }
     }
-    //parent feature of an attribute
+    /// parent feature of an attribute
     pub fn scope(&self, mut sym: Symbol) -> Symbol {
         while let Some(p) = self.parent(sym, true) {
             match sym {
@@ -285,7 +288,7 @@ impl AstDocument {
     pub fn name(&self, sym: Symbol) -> Option<Ustr> {
         self.ast.name(sym)
     }
-    //iterators over diffrent symbole types in the tree
+    /// iterators over diffrent symbole types in the tree
     pub fn all_lang_lvls(&self) -> impl Iterator<Item = Symbol> {
         self.ast.all_lang_lvls()
     }
@@ -396,8 +399,8 @@ impl AstDocument {
             _ => 0,
         }
     }
-    //Find all symboles under root with prefix path.
-    //Search branches can be aborted with a filter
+    /// Find all symboles under root with prefix path.
+    /// Search branches can be aborted with a filter
     pub fn lookup<'a, F: Fn(Symbol) -> bool + 'a>(
         &'a self,
         root: Symbol,
@@ -417,7 +420,7 @@ impl AstDocument {
             })
         })
     }
-    //Find imports for any prefix of path
+    /// Find imports for any prefix of path
     pub fn lookup_import<'a>(
         &'a self,
         path: &'a [Ustr],
@@ -441,7 +444,7 @@ impl AstDocument {
             }
         })
     }
-    //Also track the binding for path, each segment of path has some symbole bound to it
+    /// Also track the binding for path, each segment of path has some symbole bound to it
     pub fn lookup_with_binding<'a, F: Fn(Symbol) -> bool + 'a>(
         &'a self,
         root: Symbol,
@@ -461,7 +464,7 @@ impl AstDocument {
             })
         })
     }
-    // returns all Symbols with same name, used for cardinality resolving
+    /// returns all Symbols with same name, used for cardinality resolving
     pub fn get_all_entities(&self, path: &[Ustr]) -> Vec<Symbol> {
         let ustr_path = Ustr::from(path.iter().map(|s| s.to_string()).join(".").as_str());
         let mut res = vec![];
@@ -510,7 +513,7 @@ impl AstDocument {
         res
     }
 
-    //prefix of sym from root
+    /// prefix of sym from root
     pub fn prefix(&self, mut sym: Symbol) -> Vec<Ustr> {
         if matches!(sym, Symbol::Import(..)) {
             return self.ast.import_prefix(sym).into();
@@ -551,7 +554,7 @@ impl AstDocument {
     pub fn find(&self, offset: usize) -> Option<Symbol> {
         self.ast.find(offset)
     }
-    //All children under root, when merge_root_features sub features are ignored
+    /// All children under root, when merge_root_features sub features are ignored
     pub fn visit_named_children<F: FnMut(Symbol, &[Ustr]) -> bool>(
         &self,
         root: Symbol,
@@ -560,7 +563,7 @@ impl AstDocument {
     ) {
         self.visit_named_children_depth(root, merge_root_features, |sym, prefix, _| f(sym, prefix))
     }
-    //Iterate all named symbole under root and track their prefix from root
+    /// Iterate all named symbole under root and track their prefix from root
     pub fn visit_named_children_depth<F: FnMut(Symbol, &[Ustr], usize) -> bool>(
         &self,
         root: Symbol,
@@ -612,7 +615,7 @@ impl AstDocument {
     pub fn find_all_of(&self, name: Ustr) -> Vec<Symbol> {
         self.ast.find_all_of(Symbol::Root, name)
     }
-    //Iterate all named symbole under root
+    /// Iterate all named symbole under root
     pub fn visit_children_depth<F: FnMut(Symbol, u32) -> bool>(
         &self,
         root: Symbol,
@@ -645,7 +648,7 @@ impl AstDocument {
             }
         }
     }
-    //Iterate all attributes under root, and track theire associated feature
+    /// Iterate all attributes under root, and track theire associated feature
     pub fn visit_attributes<'a, F: FnMut(Symbol, Symbol, &[Ustr])>(&self, root: Symbol, mut f: F) {
         assert!(matches!(root, Symbol::Feature(..) | Symbol::Root));
         let mut owner = root;

uvls/src/core/ast/collapse.rs

@@ -1,3 +1,6 @@
+//! Transform a tree-sitter tree into the Ast ECS via recursive decent
+//! While parsing we keep a mutable state to store entities and errors
+
 use crate::core::*;
 use ast::visitor::Visitor;
 use ast::visitor::*;
@@ -19,8 +22,6 @@ impl Collapse {
     }
 }
 
-//Transform a tree-sitter tree into the Ast ECS via recursive decent
-//While parsing we keep a mutable state to store entities and errors
 #[derive(Clone)]
 struct VisitorCollapse<'a> {
     cursor: TreeCursor<'a>,
@@ -55,7 +56,7 @@ impl<'a> VisitorCollapse<'a> {
         });
     }
 
-    //get the current block header
+    /// get the current block header
     fn header(&self) -> Option<Node<'a>> {
         self.node().child_by_field_name("header")
     }
@@ -65,7 +66,7 @@ impl<'a> VisitorCollapse<'a> {
         self.levels[line] = self.current_level;
     }
 
-    // Add ranges based on self.levels vec
+    /// Add ranges based on self.levels vec
     fn calculate_ranges(&mut self) -> () {
         // Skip comments
         let first_nonzero_line = self
@@ -181,8 +182,8 @@ fn visit_top_lvl(collapse: &mut VisitorCollapse) {
         }
     }
 }
-//visits all valid children of a tree-sitter (red tree) recursively to translate them into the
-//Collapse struct
+/// visits all valid children of a tree-sitter (red tree) recursively to translate them into the
+/// Collapse struct
 pub fn visit_root(source: Rope, tree: Tree, uri: Url) -> Collapse {
     let mut c = VisitorCollapse {
         cursor: tree.walk(),

uvls/src/core/ast/def.rs

@@ -1,4 +1,4 @@
-//Basic Ast components
+//! Basic Ast components
 use enumflags2::bitflags;
 use itertools::Itertools;
 use ustr::Ustr;
@@ -48,7 +48,7 @@ impl Path {
     }
 }
 
-//Type definitions for symbols
+/// Type definitions for symbols
 #[bitflags]
 #[repr(u8)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
@@ -272,7 +272,7 @@ pub struct ExprDecl {
     pub content: Expr,
     pub span: Span,
 }
-//A symbol represents an entity in some uvl document
+/// A symbol represents an entity in some uvl document
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, enum_kinds::EnumKind)]
 #[enum_kind(SymbolKind, derive(Hash))]
 pub enum Symbol {

uvls/src/core/ast/graph.rs

@@ -1,4 +1,5 @@
-use std::borrow::{Borrow, Cow};
+//! Transform a tree-sitter tree into the Ast ECS via recursive decent
+//! While parsing we keep a mutable state to store entities and errors
 
 use crate::core::*;
 use ast::visitor::Visitor;
@@ -7,6 +8,7 @@ use check::ErrorInfo;
 use html_escape::encode_text;
 use parse::*;
 use ropey::Rope;
+use std::borrow::{Borrow, Cow};
 use tower_lsp::lsp_types::Url;
 use tree_sitter::{Node, Tree, TreeCursor};
 
@@ -61,8 +63,6 @@ impl Default for GraphNode {
     }
 }
 
-//Transform a tree-sitter tree into the Ast ECS via recursive decent
-//While parsing we keep a mutable state to store entities and errors
 #[derive(Clone)]
 struct VisitorGraph<'a> {
     cursor: TreeCursor<'a>,
@@ -84,7 +84,7 @@ impl<'a> Visitor<'a> for VisitorGraph<'a> {
 }
 
 impl<'a> VisitorGraph<'a> {
-    // Generate Graph Code:
+    /// Generate Graph Code:
 
     fn begin(&mut self) {
         self.dot.push_str(&"digraph FeatureModel {\nrankdir=\"TB\"\nnewrank=true\nnode [style=filled fontname=\"Arial Unicode MS, Arial\"];\n\n".to_string());
@@ -205,7 +205,7 @@ impl<'b> SymbolSlice for VisitorGraph<'b> {
     }
 }
 
-//parse a namespace
+/// parse a namespace
 fn visit_namespace(graph: &mut VisitorGraph) {
     loop {
         if graph.kind() == "namespace" {
@@ -317,7 +317,7 @@ fn opt_int(node: Node, state: &mut VisitorGraph) -> Option<usize> {
         None
     }
 }
-// returns cardinality for Node
+/// returns cardinality for Node
 fn opt_cardinality(node: Node, state: &mut VisitorGraph) -> Option<Cardinality> {
     let begin = node.child_by_field_name("begin");
     let end = node.child_by_field_name("end");