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