README.md 10.1 KB
Newer Older
Jerome Foret's avatar
Jerome Foret committed
1
# What is [Deep Algo](https://www.deepalgo.com/)?
Olivier HEMAR's avatar
Olivier HEMAR committed
2

Jerome Foret's avatar
Jerome Foret committed
3
As a developer, incomplete or outdated documentation is a pervasive problem.
Olivier HEMAR's avatar
Olivier HEMAR committed
4

Jerome Foret's avatar
Jerome Foret committed
5
Deep Algo is SaaS platform that **automatically** generates the documentation of your code.
Olivier HEMAR's avatar
Olivier HEMAR committed
6

Jerome Foret's avatar
Jerome Foret committed
7
## Quick Start with our Hello World!
Olivier HEMAR's avatar
Olivier HEMAR committed
8

Jerome Foret's avatar
Jerome Foret committed
9
Let's start the [Hello World](hello/hello-world.md) tutorial!
Olivier HEMAR's avatar
Olivier HEMAR committed
10

Olivier HEMAR's avatar
Olivier HEMAR committed
11
12

## Prerequisites
Olivier HEMAR's avatar
Olivier HEMAR committed
13
- Your source code is managed by a Git source control like Gitlab, Github or Bitbucket. We just need the Git URL and the read access credentials.
Olivier HEMAR's avatar
Olivier HEMAR committed
14
15
16
17

- Our **supported Web browsers**
Connect to Deep Algo from the web on your desktop anytime at https://app.deepalgo.com

Jerome Foret's avatar
Jerome Foret committed
18
19
20
21
22
> | Browser   | Requirements         |
> |:----------|----------------------|
> | Chrome    | Version 79 or above  |
> | Chromium  | Version 63 or above  |
> | Firefox   | Latest               |
Olivier HEMAR's avatar
Olivier HEMAR committed
23
24
25
26
27
28
29
30
31
32
33
34

- Unsupported browsers
To focus on delivering the best possible experience in Deep Algo, it is necessary
to keep the list of supported browsers short.

When a browser is no longer supported, we stop fixing pesky bugs and issues.

- **Mobile browsers**
We're working hard to have the solution working on mobile and tablets, but as
far as now we do not support the use on mobile because the user experience is
not good. We'll keep you inform as soon as this feature is available.

Olivier HEMAR's avatar
Olivier HEMAR committed
35

Olivier HEMAR's avatar
Olivier HEMAR committed
36

Olivier HEMAR's avatar
Olivier HEMAR committed
37
## Use cases
Jerome Foret's avatar
Jerome Foret committed
38
- document as a code (Docs as Code) in english : add `// @deepalgo` comment in your code and get the documentation (see [guidelines](ci-cd/guidelines-add-comment.md)) 
Olivier HEMAR's avatar
Olivier HEMAR committed
39
40
41
- integrate the documentation workflow in your DevOps toolchain
- keep this documentation updated by integrating this workflow in your CI
- get an interactive documentation to simulate outcomes depending on selected conditions
Olivier HEMAR's avatar
Olivier HEMAR committed
42

Jerome Foret's avatar
Jerome Foret committed
43
## Get deeper
Olivier HEMAR's avatar
Olivier HEMAR committed
44
45
Following is the overall workflow:
- [Connect](connect/connect.md) the Deep Algo platform (https://app.deepalgo.com)
Olivier HEMAR's avatar
Olivier HEMAR committed
46
- [Create](projects/create.md) a project
Olivier HEMAR's avatar
Olivier HEMAR committed
47
- [Launch](pipelines/pipelines.md) a documentation
Jerome Foret's avatar
Jerome Foret committed
48
- [Read](docs/docs.md) a documentation
Olivier HEMAR's avatar
Olivier HEMAR committed
49
- [Automate your documentation](ci-cd/ci-cd.md)
Olivier HEMAR's avatar
Olivier HEMAR committed
50
51
52

## The project page

Olivier HEMAR's avatar
Olivier HEMAR committed
53
The project page contains different menu to manage :
Olivier HEMAR's avatar
Olivier HEMAR committed
54
55
56
57
- [Settings](settings/settings.md) Menu
- [Docs](docs/docs.md) Menu ([Docs as Code](docs/docs.md#doc-as-code), [Interactive doc](docs/docs.md#interactive-doc), [Doc on demand](docs/docs.md#doc-on-demand))
- [Pipelines](pipelines/pipelines.md) Menu
- [CI/CD](ci-cd/ci-cd.md) Menu
Olivier HEMAR's avatar
Olivier HEMAR committed
58
59
60

## Manage your profile

Olivier HEMAR's avatar
Olivier HEMAR committed
61
62
Learn how to [manage your profile](profile/profile.md).

Olivier HEMAR's avatar
Olivier HEMAR committed
63
64
65
66
# Support and Help Center

We use Intercom Chat both to enable real-time communication with our support team and fix your issues as soon as possible.

Olivier HEMAR's avatar
Olivier HEMAR committed
67
![Intercom](img/intercom_chatbot.png)
Olivier HEMAR's avatar
Olivier HEMAR committed
68

Olivier HEMAR's avatar
Olivier HEMAR committed
69
Feel free to contact us by clicking the Chatbot at the right bottom of your browser.
Olivier HEMAR's avatar
Olivier HEMAR committed
70

Olivier HEMAR's avatar
Olivier HEMAR committed
71
72
73
74
# Subscription plan

To get all information about our subscription plan, feel free to visit our website (https://www.deepalgo.com).

Olivier HEMAR's avatar
Olivier HEMAR committed
75
76
# What's new?

Jerome Foret's avatar
Jerome Foret committed
77
#### 20.1.8
Olivier HEMAR's avatar
Olivier HEMAR committed
78
What an easy question! Everything is new!  Enjoy!
Olivier HEMAR's avatar
Olivier HEMAR committed
79

Jerome Foret's avatar
Jerome Foret committed
80
The last version is 20.1.8. You can see the version you use by clicking on the
Olivier HEMAR's avatar
Olivier HEMAR committed
81
information icon ![information-icon](img/information-icon.png).
Olivier HEMAR's avatar
Olivier HEMAR committed
82

Olivier HEMAR's avatar
Olivier HEMAR committed
83
84
# What's next?

Olivier HEMAR's avatar
Olivier HEMAR committed
85
What about the next development of Deep Algo?
Olivier HEMAR's avatar
Olivier HEMAR committed
86

Olivier HEMAR's avatar
Olivier HEMAR committed
87
Help us to develop the most valuable features.
Olivier HEMAR's avatar
Olivier HEMAR committed
88

Olivier HEMAR's avatar
Olivier HEMAR committed
89
![Intercom](img/intercom_chatbot.png)
Olivier HEMAR's avatar
Olivier HEMAR committed
90

Olivier HEMAR's avatar
Olivier HEMAR committed
91
Give us some feedbacks using the Chatbot at the bottom right corner.
Olivier HEMAR's avatar
Olivier HEMAR committed
92

Olivier HEMAR's avatar
Olivier HEMAR committed
93
94
95
96
Some ideas:
- C# language
- ….

Olivier HEMAR's avatar
Olivier HEMAR committed
97
# Frequently Asked Questions (FAQ)
Jerome Foret's avatar
Jerome Foret committed
98
99
100
101
102
103
104
105
## How does it work?
We have replicated the steps a developer would do if he had to produce a documentation: 

 1. Reverse engineer the code base to get a universal representation in our own language : Unified Meta Model
 2. Analyse the parsed code at a technical level: who's calling who? data flow, etc ...
 3. Make it understandable: draw simple diagrams, summarize in english and write  down the major results as simple formuas
 
## What can we understand and therefore document?
Jerome Foret's avatar
Jerome Foret committed
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
- As of today, we can document **JAVA** code only. We are beta testing **C#**.
- We can document pieces of code where a `@deepalgo` comment lies. To understand our **DocAsCode** principles visit the [guidelines](ci-cd/guidelines-add-comment.md).
- We are capable to document object oriented programming. Therefore not only variables with intrinsec types are documentable but also complex data structures. 
- We inline all methods where they are called. That is to say: in the following exemple: 

  ```java
  /// file Main.java
  public class Main {
      // @deepalgo
      public static int main(String[] argv){
        Foo f = new Foo(argv[0]);
        return f.run()
      }
  }
  /// file Foo.java
  public class Foo{
    private String name;
    public Foo(String name){
      this.name = name;
    }
    public int run(){
      // a butifull code that itself delegates to 
      // other pieces of code
    }
  }
  ```
  You only need to tag the `main` method with `// @deepalgo` comment, we will dive in the algorithm to understand what it really does.

- We understand loops: `for`, `while` and `forEach`, even accross inlined methods 
- We understand native arrays: `Foo[] listOfFoo`
- We partially handle non native arrays such as `List` or `HashMap` with following limitations: 
  * Only for **JAVA**
  * Only for the followig list of operations `add, addAll, remove, removeAll, sort, clear, put, putAll, putIfAbsent, replace, replaceAll`
- We handle recursive calls: for instance a recursive implementation of the `factorial(n)` function would lead to : `factorial(n) = (n * (n-1)*factorial(n-1-1))`
  * The documentation may fail or timeout if the recursion gets too complex : multiple recursive calls inside each other
- We handle conditions by providing an interactive logical flow graph. The conditions are gathered accross all inlined methods.
Jerome Foret's avatar
Jerome Foret committed
142
143
144
145
146
147
148
149
150
151
152
153

## What can't we understand... and therefore can't document?
- We cannot analyse the external components of your code (because we can't analyse the code we don’t have :-) ). Actually this is not a real limitation... indeed let's take this piece of code:

```c++
#include "iostream"
int main(int argc, char * [] argv){
  printf("Hello world!");
  return 0;
}
```

Jerome Foret's avatar
Jerome Foret committed
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
If we were to explain what `printf` does, we would ultimately end up into saying that: "the application shifts a bunch of buffers" ... which is not false, but totaly useless.

- So far output parameters are not handled : 
 ```java
  /// file Main.java
  public class Main {
      // @deepalgo
      public static int main(String[] argv){
        Foo f = new Foo(argv[0]);
        String someVariable = "";
        f.run(someVariable);
        System.out.println(someVariable);
        return 0
      }
  }
  /// file Foo.java
  public class Foo{
    private String name;
    public Foo(String name){
      this.name = name;
    }
    public void run(String outParam){
      outParam = "Hellow world";
    }
  }
  ```
The `someVariable` will not be replaced by the value `"Hellow world"`

- Some methods are hard to properly inline. Indeed in the very simple explemple below:
```java
  /// file Main.java
  public class Main {
      // @deepalgo
      public static int main(String[] argv){
        Foo f = new Foo(argv[0]);        
        f.run(argv.length);        
        return 0
      }
  }
  /// file Foo.java
  public class Foo{
    private String name;
    public Foo(String name){
      this.name = name;
    }
    public Double run(Double p){
      return p * this.name.size();
    }
    public Double run(String p){
      return p.size() * this.name.size();
    }
  }
  ```
The call to `run` is ambiguous for us... `argv.length` is not known to Deep Algo, therefore we cannot infer the type of `length` (it seam obvious for a human ... but it is not for a machine). Since it exists 2 implementations of the `run` we may inline the first one or the last one.
Jerome Foret's avatar
Jerome Foret committed
208

Olivier HEMAR's avatar
Olivier HEMAR committed
209
210
211
212
213
- Licenses: There is great to deal with this pain on the market!

- Class Diagrams: were sure you can find that in your IDE.

- Your Code of conduct :-)
Olivier HEMAR's avatar
Olivier HEMAR committed
214

Jerome Foret's avatar
Jerome Foret committed
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
## It seams that my result is not fully inlined?
This case may rise when the call is not linked to any method though it should be. Most probably a lack of context or a real bug on our side.
When loops are involved, as follows (for instance):

```java
  /// file Main.java
  public class Main {
      // @deepalgo
      public static int main(String[] argv){
        Foo f = new Foo(argv[0]);
        // @deepalgo
        Double res = 1.0;
        for(/* some arguments here */){
          res = f.run(res * i)
        }
        return 0
      }
  }
  /// file Foo.java
  public class Foo{
    private String name;
    public Foo(String name){
      this.name = name;
    }
    public Double run(Double p){
      return p * this.name.size();
    }
  }
  ```
The final result 

## Why is my documentation empty?
Mostlikely because there is nothing relevant to document. Normally, Deep Algo tries to avoid such irrelevant methods, to reduce noise, but sometimes the code base itself is confusing

## Why results of a keyword in the search bar do not involve the keyword itself?
Deep Algo indexes your documented methods by taking into account the fully inlined algorithm.  Meaning that the keyword may be very relevant (and therefore pop in the results) though it appears much deeper than in the method itself.

Jerome Foret's avatar
Jerome Foret committed
252
## Which languages can be analyzed?
Olivier HEMAR's avatar
Olivier HEMAR committed
253
254
255
Deep Algo is language agnostic: it's independent of any specific programming
language. We only need to implement the grammar of the language.

Jerome Foret's avatar
Jerome Foret committed
256
Deep Algo can currently manage applications in **Java**.
Olivier HEMAR's avatar
Olivier HEMAR committed
257

Jerome Foret's avatar
Jerome Foret committed
258
We're working hard to add new languages.
Olivier HEMAR's avatar
Olivier HEMAR committed
259

Jerome Foret's avatar
Jerome Foret committed
260
## How long does an analysis last?
Jerome Foret's avatar
Jerome Foret committed
261
Deep Algo is able to analyze 50k lines of a java code in around 3 hours, yet this may vary drastically depending on your code.
Olivier HEMAR's avatar
Olivier HEMAR committed
262
263
264
265

## What's your confidence level in an analysis?
For each analysis, we get an understanding indicator with a detailed report of
all the files, lines of code Deep Algo didn't understand.
Jerome Foret's avatar
Jerome Foret committed
266

Jerome Foret's avatar
Jerome Foret committed
267
268
# Known issues
Despite the aforementioned limitations, we know we have some issues, and we are already working hard on it: 
Jerome Foret's avatar
Jerome Foret committed
269
- In the final documentation the sentence "list of MyClass" appears frequently, yet no array or list are involved.
Olivier HEMAR's avatar
Olivier HEMAR committed
270
271
272
273
274
275

All the known issues are gathered as an issue just here: 
https://gitlab.com/deepalgo/deepalgo-doc/known-issues/-/issues

Feel free to add any issue you could identifiy. Thks in advance for your collaboration !

Jerome Foret's avatar
Jerome Foret committed
276
277
278
279
280