Update documentation by g-krisztian · Pull Request #238 · Flexiana/framework

g-krisztian · 2022-10-06T10:35:45Z

Title:

Update documentation for release v0.5.0-rc3

Description

Updated markdown files, and build-docs.sh to support UML integration
Using forked codox for support markdown anchors - See in contribution.md

Tester info

Pls go through as an english teacher 😉

Completion Checklist

Add description of the changes made here to the changelog file
Update the documentation as necessary

soulflyer · 2022-10-07T15:25:38Z

doc/contribution.md

+
+## Coding standards
+
+Please follow `clj-style` and `kondo` instructions. `Kibit` isn't a showstopper, but PRs are more welcomed if not


"...more welcome if they don't break kibit.'

soulflyer · 2022-10-07T15:26:21Z

doc/contribution.md

+
+## Submitting a PR
+
+Before you are submitting a PR be sure:


"Before you submit a PR be sure:"

soulflyer · 2022-10-07T15:28:06Z

doc/contribution.md

+- the PR has an issue in GitHub, with a good description
+- you have added tests
+- you provided an example project for a new feature
+- All PRs need at least two approvals


This doesn't really belong in a list of things to check. Maybe just move it to its own paragraph after the list.

soulflyer · 2022-10-07T15:29:06Z

doc/contribution.md

+
+## Generating API Docs
+
+This is done with using [mermaid-cli](https://github.com/mermaid-js/mermaid-cli) and a forked version


either "with" or "using". Not both.

soulflyer · 2022-10-07T15:29:53Z

doc/contribution.md

+This is done with using [mermaid-cli](https://github.com/mermaid-js/mermaid-cli) and a forked version
+of [Codox](https://github.com/Flexiana/codox).
+
+We're using mermaid-cli for render UML-diagrams in markdown files, see the `doc/conventions_template.md` for example.


"...mermaid-cli to render..."

soulflyer · 2022-10-07T15:30:20Z

doc/contribution.md

+of [Codox](https://github.com/Flexiana/codox).
+
+We're using mermaid-cli for render UML-diagrams in markdown files, see the `doc/conventions_template.md` for example.
+These files need to be added to the `/script/build-docs.sh` . For using it you need to have `npx`.


"To use it you need...."

soulflyer · 2022-10-07T15:31:37Z

doc/conventions.md

+
+## Overview

+The diagram bellow gives you an overview, how a request is processed in Xiana based applications.


"... an overview of how a request..."

soulflyer · 2022-10-07T15:32:33Z

doc/conventions.md


-An interceptor is a pair of unary functions. Each function must recieve and return a state map. You can look at it as on an analogy to AOP's around aspect, or as on a pair of middlewares. They work mostly the same way as [pedestal](http://pedestal.io/reference/interceptors) and [sieppari](https://github.com/metosin/sieppari) interceptors.
-Xiana provides a set of base [interceptors](interceptors.md), for the most common use cases. 
+An interceptor is a pair of unary functions. Each function must recieve and return a state map. You can look at it as on


"look at it as an analogy...."

soulflyer · 2022-10-07T15:33:51Z

doc/conventions.md

+## Interceptors error handling:
+
+The interceptor executor handles the exceptional states like sieppari does. If an exception happens, it tries to handle
+first in the same interceptor. If it has and `:error` handler, it will call it, otherwise it'll search for `:error`


"If it has an..."

soulflyer · 2022-10-07T15:34:42Z

doc/conventions.md

+
+The interceptor executor handles the exceptional states like sieppari does. If an exception happens, it tries to handle
+first in the same interceptor. If it has and `:error` handler, it will call it, otherwise it'll search for `:error`
+handlers for the beginning of the interceptor queue. When and `:error` function found, and matched with the given


Should "for" be "from"?
"When an :error function..."

soulflyer · 2022-10-07T15:36:20Z

doc/conventions.md

+The interceptor executor handles the exceptional states like sieppari does. If an exception happens, it tries to handle
+first in the same interceptor. If it has and `:error` handler, it will call it, otherwise it'll search for `:error`
+handlers for the beginning of the interceptor queue. When and `:error` function found, and matched with the given
+exception, the executor calls the queue `:leave` functions in reserved order, where the handler has been found.


maybe "...calls the queue of :leave functions in reverse order from where the handler was found.

soulflyer · 2022-10-07T15:36:47Z

doc/conventions.md

+handlers for the beginning of the interceptor queue. When and `:error` function found, and matched with the given
+exception, the executor calls the queue `:leave` functions in reserved order, where the handler has been found.
+
+This diagram shows how the error cases handled:


"..cases are handled:"

soulflyer · 2022-10-07T15:38:07Z

doc/conventions_template.md

+- request-data
+- response
+
+This structure is very volatile, will be updated quite often on the application's life cycle.


"...volatile, and will be updated..."

soulflyer · 2022-10-07T15:38:33Z

doc/conventions_template.md

+
+- Interceptors:
+
+  Add, consumes or remove information from the state map. More details in [Interceptors](#interceptors) section.


soulflyer · 2022-10-07T15:39:31Z

doc/conventions_template.md

+
+The action conventionally is the control point of the application flow. This is the place were you can define how the
+rest of your execution flow would behave. Here you can provide the database query, restriction function, the view, and
+the additional side effect functions are you want to execute.


"...functions that you want to..."

soulflyer · 2022-10-07T15:41:12Z

doc/conventions_template.md

+
+## Dependencies
+
+Modules can depend on external resources, configurations, as well as on other modules. These dependencies are added to


"...external resources and configurations..." (or maybe and/or)

soulflyer · 2022-10-07T15:42:51Z

doc/conventions_template.md

+
+## Interceptors
+
+An interceptor is a pair of unary functions. Each function must recieve and return a state map. You can look at it as on


"...look at it as an analogy..."

soulflyer · 2022-10-07T15:44:25Z

doc/conventions_template.md

+The interceptor executor handles the exceptional states like sieppari does. If an exception happens, it tries to handle
+first in the same interceptor. If it has and `:error` handler, it will call it, otherwise it'll search for `:error`
+handlers for the beginning of the interceptor queue. When and `:error` function found, and matched with the given
+exception, the executor calls the queue `:leave` functions in reserved order, where the handler has been found.


Same as the non template version.

soulflyer · 2022-10-07T15:46:51Z

doc/getting-started.md

 ### 2. Set initial value of re-frame database

-File *src/frontend/todo_app/db.cljs* contains initial value of re-frame databse. Inside of this file replace value of *default-db* to following:
+File *src/frontend/todo_app/db.cljs* contains initial value of re-frame databse. Inside of this file replace value of *


"...change the value of default-db to the following..."

soulflyer · 2022-10-07T15:51:36Z

docs/0.5.0-rc2/contribution.html

@@ -0,0 +1,108 @@
+<!DOCTYPE html PUBLIC ""


This will need regenerating from the corrected .md file?

soulflyer

LGTM

g-krisztian added 7 commits September 27, 2022 11:13

Update documentation

2573260

Update version

0370d06

Add version-docs

0be8e20

Add source uri

26aba45

update README.md xiana logo

71a4edc

Merge branch 'main' into update_documentation

08d34d2

Update docs

e6fad22

soulflyer reviewed Oct 7, 2022

View reviewed changes

doc/contribution.md Outdated

## Submitting a PR

Before you are submitting a PR be sure:

Copy link

Contributor

soulflyer Oct 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Before you submit a PR be sure:"

soulflyer reviewed Oct 7, 2022

View reviewed changes

Language review @soulflyer

32e99f8

soulflyer reviewed Nov 7, 2022

View reviewed changes


		## Coding standards

		Please follow `clj-style` and `kondo` instructions. `Kibit` isn't a showstopper, but PRs are more welcomed if not


		## Generating API Docs

		This is done with using [mermaid-cli](https://github.com/mermaid-js/mermaid-cli) and a forked version


		## Overview

		The diagram bellow gives you an overview, how a request is processed in Xiana based applications.


		- Interceptors:

		Add, consumes or remove information from the state map. More details in [Interceptors](#interceptors) section.


		## Dependencies

		Modules can depend on external resources, configurations, as well as on other modules. These dependencies are added to


		## Interceptors

		An interceptor is a pair of unary functions. Each function must recieve and return a state map. You can look at it as on

Comments

Conversation

g-krisztian commented Oct 6, 2022

Title:

Description

Tester info

Completion Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soulflyer Oct 7, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soulflyer left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

soulflyer Oct 7, 2022 •

edited

Loading