Create user guide for the viewer server #865

csordasmarton · 2017-09-01T14:32:14Z

Closes #737

whisperity

Information is an uncountable word. Meta informations is thus grammatically incorrect.

On review_status_message.png (Damn GitHub, why can't I inline (in-pixel?) annotate images?!?!) I'd rather write Review status details instead of "meta" and "actual".

whisperity · 2017-09-01T14:36:15Z

www/scripts/codecheckerviewer/codecheckerviewer.js

+        this.userguide = new ContentPane({
+          title : 'User guide',
+          closable : true,
+          href  : 'userguide/doc/html/userguide.html',


How does this handle if the user guide is missing because it failed to generate? The build script only issues a warning in this case.

If the user guide is missing, dojo will handle it:

Xazax-hun · 2017-09-04T13:12:22Z

www/userguide/userguide.md

+<span class="customIcon severity-low"></span>  | Low | **TODO** | _deadcode.DeadStores, misc-unused-parameters, etc._ |
+<span class="customIcon severity-medium"></span>  | Medium | **TODO** | _unix.Malloc, core.uninitialized.Assign, etc._ |
+<span class="customIcon severity-high"></span>  | High | **TODO** | _core.DivideZero, core.NullDereference, cplusplus.NewDelete, etc._ |
+<span class="customIcon severity-critical"></span>  | Critical | **TODO** | **TODO** |


Are these TODOs intentional or just oversight?

gyorb · 2017-09-04T16:28:16Z

scripts/build_package.py

@@ -700,6 +700,11 @@ def build_package(repository_root, build_package_config, env=None):
    target = os.path.join(package_root, package_layout['www'])
    copy_tree(source, target)

+    # Run doxygen.


Why do we call doxygen here? It is called in the Makefile

codechecker/Makefile

Line 20 in de1ab87

gen-docs: build_dir

gyorb · 2017-09-04T16:30:24Z

www/userguide/Doxyfile

@@ -0,0 +1,12 @@
+PROJECT_NAME           = "CodeChecker"


Couldn't we use the top level Doxyfile?

The top level Doxygen file uses doxygen own header and footer files. This way the html file which the doxygen was generated looks like this:

It contains extra style sheets and javascript files. If I'm opening the user guide in the CodeChecker, I'm getting a 404 error because these files doesn't exists in the web root directory.
This is the reason why I used a separate Doxygen file.

gyorb · 2017-09-04T16:31:00Z

www/style/doxygen.css

@@ -0,0 +1,271 @@
+.doxgen { font:400 14px/22px Roboto,sans-serif;background-color:#FFF;color:#000;margin:0; }


Why is this file checked in? This was generated by doxygen right?

bruntib · 2017-09-25T09:19:15Z

www/userguide/userguide.md

+\tableofcontents
+
+**CodeChecker** is a static analysis infrastructure built on the [LLVM/Clang
+Static Analyzer](http://clang-analyzer.llvm.org) toolchain, replacing


Is CodeChecker really going to replace scan-build, or is it an alternative tool with much more functionalities? And if it really replaces scan-build, will the user guide reader know what scan-build was originally?

bruntib · 2017-09-25T09:22:34Z

www/userguide/userguide.md

+You can delete multiple runs by selecting them and clicking on the Delete
+button. It will remove the run and all related data from the database.
+
+\subsection run_order Reorder runs


"Sorting runs"

bruntib · 2017-09-25T09:29:11Z

www/userguide/userguide.md

+[`scan-build`](http://clang-analyzer.llvm.org/scan-build.html) in a Linux or
+macOS (OS X) development environment.
+
+\section list_of_runs List of runs


Maybe we should write about these concepts. It may not be completely intuitive what a product or run (update mode, etc.) is. However I think the description of these should go to another user guide, because if the user is already on the web interface then he or she is done with storing results to a run.

bruntib · 2017-09-25T09:34:16Z

www/userguide/userguide.md

+![Report navigation tree](images/userguide/report_navigation_tree.png)
+
+\subsection button_pane Button pane
+Button Pane contains several items which helps you to change or get some


"... which help you ..."

bruntib · 2017-09-25T09:36:40Z

www/userguide/userguide.md

+![Checker documentation](images/userguide/checker_documentation.png)
+
+\subsubsection review_status Review status
+Reports can be assigned a review status of Unreviewed, Confirmed bug, False


Reports or bugs can be assigned a review status (detection status, comment, etc.)? If this information belongs to a bug then what is the connection between the bugs and reports? (unique mode)

bruntib · 2017-09-25T09:37:58Z

www/userguide/userguide.md

+to something else in the report details view above the file view.
+![Unreviewed](images/userguide/review_status_unreviewed.png)
+
+If you changed the review status, you can optionally explain the reason why do


"... why you changed it ..."

bruntib · 2017-09-25T09:38:33Z

www/userguide/userguide.md

+![Change review status](images/userguide/review_status_change.png)
+
+If somebody has already changed the review status from the default one, you can
+see extra informations (who changed the review status, when and why) beside


"information" has no plural.

bruntib · 2017-09-25T09:40:51Z

www/userguide/userguide.md

+If somebody has already changed the review status from the default one, you can
+see extra informations (who changed the review status, when and why) beside
+the review status selector by hovering on the message icon. This message icon is
+hided by default if nobody has changed the review status.


bruntib · 2017-09-25T09:41:54Z

www/userguide/userguide.md

+![Review status message](images/userguide/review_status_message.png)
+
+\subsection bug_path_view Bug path view
+Bug path shows the path of the actual report.


What is a path? A few words about symbolic execution, bug path and bug event?

bruntib · 2017-09-25T09:45:18Z

Maybe it would be a good idea to extend this documentation based on the "release notes" description: https://github.com/Ericsson/codechecker/releases/tag/v6.0.

bruntib · 2017-10-02T13:10:23Z

www/userguide/userguide.md

+
+After enabling the administrative actions in the top right corner, click
+*Add new product*, then fill the form presented. The values that need to be
+filled here are the same as the arguments for `CodeChecker cmd products add`.


We should also mention that these buttons are visible only for the super user.

bruntib · 2017-10-02T13:11:28Z

www/userguide/userguide.md

+\subsection userguide_managing_products Managing products
+![Products](images/userguide/products.png)
+
+After enabling the administrative actions in the top right corner, click


What do "administrative actions" mean? This term is used several times in the text without its meaning being defined.

bruntib · 2017-10-02T13:13:53Z

www/userguide/userguide.md

+\subsection Managing permissions
+* Server-wide permissions can be edited by clicking *Edit global permissions*.
+* Product-level permissions can be edited by clicking the edit icon for the
+product you want to configure the permissions for.


"for" is already there before "the product".

bruntib · 2017-10-02T13:19:55Z

www/userguide/userguide.md

+Clicking *OK* will save the changes to the database.
+
+\section list_of_runs List of runs
+List page contains the analysis runs available on the server.


"... on the server under the selected product."

bruntib · 2017-10-02T13:35:58Z

www/userguide/userguide.md

+![Same reports](images/userguide/same_reports.png)
+
+\subsection userguide_bug_path_view Bug path view
+Bug path shows the path of the actual report.


"Some checkers are able to follow the execution path along the control flow of the program. If a bug appears on any of these paths then CodeChecker is able to present the full path on which this so called symbolic execution reached the place of error. This path can be checked in this bug path view."

whisperity · 2017-10-03T06:49:03Z

Can't send review-like comments from phone.

Perhaps, considering the Web client user guide contains information about the product system, @csordasmarton could you please introduce a button next to the Show administration one visible to everyone, having some Dojo-standard ? icon on the product homepage which also opens the user guide? (If possible with a HTML anchor, at the product-specific parts?)

whisperity · 2017-10-03T07:11:22Z

Actually, I think it's even better if the whole of the "main menu" is moved to a separate module and the users are able to use the whole menu (credits, report bug shortcut, etc.) on the product homepage too.

whisperity · 2017-10-03T17:37:25Z

libcodechecker/server/routing.py

@@ -19,6 +19,7 @@
                         'fonts',
                         'images',
                         'scripts',
+                         'userguide',


Keep an alphabetical order here, it makes maintaining stuff easier.

csordasmarton · 2017-10-04T11:44:38Z

I rewrote the userguide.md file by using md file rules. This way the github will show this file contant in a better way.

For more information see:
https://github.com/csordasmarton/codechecker/blob/user_guide/www/userguide/userguide.md

whisperity · 2017-10-04T22:37:49Z

On the image that explains the BugViewer.js features (not the layout, but the features), there is a seemingly dangling CHECKER ID arrow that points to... the CodeChecker version in the web page header.

csordasmarton · 2017-10-05T07:29:44Z

That's points to the checker name. Maybe that wasn't a good idea to name it to CHECKER ID. I renamed it to CHECKER NAME.

gyorb · 2017-10-05T08:09:33Z

scripts/build_package.py

+    copy_tree(source, target, [userguide_images])
+    copy_tree(userguide_images, os.path.join(target, 'images'))
+
+    # Run doxygen.


A separate make file target would be better, or please extend the current docs target to generate html from the markdown.

I agree here. Even if it requires a separate Doxyfile to exist. Also, the build_script.py does not run in parallel, while make can make the build distributed if multiple threads are allowed. (Not that documentation generation should be paralellised so much, I know.)

whisperity · 2017-10-05T08:38:07Z

@csordasmarton www/userguide/images/bug_view.png:

whisperity

I read through the guide and also ran language checking tools on it.

whisperity · 2017-10-05T08:42:03Z

www/userguide/userguide.md

+
+## <a name="userguide-filter-runs"></a> Filter runs
+You can filter runs by run name using the input box above the run list table.
+The filter is working **case insensitive** and doing an **infix search**. If we


The filter is ~~working~~ case insensitive.

Perhaps infix search should be rephrased to substring matching?

whisperity · 2017-10-05T08:43:01Z

www/userguide/userguide.md

+## <a name="userguide-filter-runs"></a> Filter runs
+You can filter runs by run name using the input box above the run list table.
+The filter is working **case insensitive** and doing an **infix search**. If we
+start typing some keyword in this input box, the list are being _filtered


Is it a keyword? Maybe some phrase or name part˛?

The list ~~are~~ is automatically filtered as we type in.

whisperity · 2017-10-05T08:43:17Z

www/userguide/userguide.md

+
+## <a name="userguide-sorting-runs"></a> Sorting runs
+It is possible to change the order of the runs by clicking on a cell at header
+of the run list table. For example you can sort the run list by the number of


For example, (needs a comma afterwards)

whisperity · 2017-10-05T08:43:38Z

www/userguide/userguide.md

+reports with the given detection status to check only *Unresolved*, *Resolved*,
+etc. reports.
+- [**Severity**](#userguide-severity-levels): The nature of the bugs is sorted
+in different severity levels. For example a division by zero or a null pointer


For example here too.

whisperity · 2017-10-05T08:43:53Z

www/userguide/userguide.md

+- **Detection date**: A date interval can also restrict the list of displayed
+bug reports. In this field you can choose the date of detection or fixing.
+- **File**: You can choose a set of files to restrict the list of bug reports.
+- **Checker name**: If you are instrested in specific type of bugs then here you


instrested -> interested

whisperity · 2017-10-05T08:44:34Z

www/userguide/userguide.md

+- **Baseline**: The runs against which you want to check the difference.
+- **Newcheck**: The runs which you want to compare against the baseline runs.
+- **Diff type**: Here you can set if you'd like to see the bugs which appear
+only in the baseline, newcheck or both.


I would format baseline and newcheck as baseline or as baseline (monospace or italic)

whisperity · 2017-10-05T08:45:08Z

www/userguide/userguide.md

+Reports can be assigned a review status of Unreviewed, Confirmed bug, False
+positive, Intentional, along with an optional comment on why this status was
+applied.
+- <span class="customIcon review-status-unreviewed"></span>  **Unreviewed**


Extra space between > and *.

whisperity · 2017-10-05T08:46:20Z

www/userguide/userguide.md

+
+## <a name="userguide-bug-path-view"></a> Bug path view
+Some checkers are able to follow the execution path along the control flow of
+the program. If a bug appears on any of these paths then CodeChecker is able to


According to the spellchecker: "If your sentence begins with a condition, insert a comma in front of the independent clause."

So a , between paths and then.

whisperity

Nice work, I really like this guide to be available at a fingertip. ❤️

We just now need to make sure to keep this up-to-date too, when the UI changes.

Two concerns I have apart from the specifics discussed earlier:

The original SVGs for the images should be retained somehow, so that edits can be made easily later on.
I would also somehow put a very generic phrase, with > as a prefix (Markdown quote syntax), at the beginning of the in-browser user guide, which directly links to GitHub. Something along the lines of More descriptions and guides available [on GitHub](http://github.com/...). The text is just provisionary, but somehow I think it would be nice if the "one-shot user" (a member of a programmer team who does not really know how to use the analyzer part of CodeChecker) would see that this tool is capable not just to present results (even though that is one of the main and most developed part as of now). So just some sort of a handrail... "Hey, this website is cool, but you can run the analysis yourself, read more here!". Something like this.

whisperity

Did the image I posted about earlier intentionally disappear?

whisperity · 2017-10-06T08:18:43Z

www/userguide/Makefile.manual

@@ -0,0 +1,9 @@
+all: userguide
+
+# pack binary


The comments in these files are useless, and derailing. Why is this called Makefile.manual instead of just simply Makefile?

csordasmarton · 2017-10-06T08:49:22Z

@whisperity I removed that image because we didn't use that anywhere.

whisperity · 2017-10-06T08:53:41Z

www/userguide/Makefile

+	doxygen ./Doxyfile
+
+clean:
+	rm -rf $(BUILD_DIR)


Are you sure this variable is what you intend it to be? Is this variable even defined to a proper value? Look at how Makefile chains in api are laid out!

csordasmarton requested a review from whisperity September 1, 2017 14:32

whisperity added this to the 6.0 pre4 milestone Sep 1, 2017

whisperity added enhancement 🌟 documentation 📖 Changes to documentation. WIP 💣 Work In Progress labels Sep 1, 2017

whisperity requested changes Sep 1, 2017

View reviewed changes

whisperity reviewed Sep 1, 2017

View reviewed changes

Xazax-hun reviewed Sep 4, 2017

View reviewed changes

gyorb suggested changes Sep 4, 2017

View reviewed changes

whisperity force-pushed the version6 branch from 14a3ed2 to 4c8f84d Compare September 5, 2017 08:09

csordasmarton changed the base branch from version6 to master September 5, 2017 08:11

csordasmarton force-pushed the user_guide branch from 3b2208a to 571a9cb Compare September 5, 2017 08:38

dkrupp modified the milestones: 6.0 pre4, 6.0.1 Sep 18, 2017

gyorb removed this from the release 6.0.1 milestone Sep 21, 2017

bruntib reviewed Sep 25, 2017

View reviewed changes

csordasmarton force-pushed the user_guide branch 3 times, most recently from f6c5b3d to 03570be Compare October 2, 2017 12:58

csordasmarton requested a review from bruntib October 2, 2017 12:58

bruntib reviewed Oct 2, 2017

View reviewed changes

csordasmarton force-pushed the user_guide branch from 03570be to 4424dcd Compare October 3, 2017 11:16

whisperity requested changes Oct 3, 2017

View reviewed changes

csordasmarton force-pushed the user_guide branch 4 times, most recently from ce73a5c to 31593e8 Compare October 4, 2017 11:08

csordasmarton requested review from bruntib, whisperity and gyorb October 4, 2017 11:44

csordasmarton force-pushed the user_guide branch from 31593e8 to eb37e4e Compare October 4, 2017 11:46

bruntib approved these changes Oct 4, 2017

View reviewed changes

csordasmarton force-pushed the user_guide branch from eb37e4e to 287901b Compare October 5, 2017 07:25

gyorb suggested changes Oct 5, 2017

View reviewed changes

whisperity requested changes Oct 5, 2017

View reviewed changes

csordasmarton force-pushed the user_guide branch 3 times, most recently from d345b4b to 132c7c4 Compare October 5, 2017 13:19

csordasmarton requested review from whisperity and gyorb October 6, 2017 07:22

whisperity requested changes Oct 6, 2017

View reviewed changes

csordasmarton force-pushed the user_guide branch from 132c7c4 to fc4c493 Compare October 6, 2017 08:48

csordasmarton requested a review from whisperity October 6, 2017 08:49

whisperity reviewed Oct 6, 2017

View reviewed changes

Create user guide for the viewer server

fc22716

csordasmarton force-pushed the user_guide branch from fc4c493 to fc22716 Compare October 6, 2017 09:50

csordasmarton requested a review from whisperity October 6, 2017 09:50

whisperity approved these changes Oct 6, 2017

View reviewed changes

bruntib merged commit 43685be into Ericsson:master Oct 9, 2017

csordasmarton deleted the user_guide branch October 13, 2017 07:05

		@@ -0,0 +1,271 @@
		.doxgen { font:400 14px/22px Roboto,sans-serif;background-color:#FFF;color:#000;margin:0; }

Create user guide for the viewer server #865

Create user guide for the viewer server #865

Conversation

csordasmarton commented Sep 1, 2017

whisperity left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bruntib commented Sep 25, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whisperity commented Oct 3, 2017

whisperity commented Oct 3, 2017

Choose a reason for hiding this comment

csordasmarton commented Oct 4, 2017

whisperity commented Oct 4, 2017

csordasmarton commented Oct 5, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whisperity commented Oct 5, 2017

whisperity left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whisperity left a comment

Choose a reason for hiding this comment

whisperity left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

csordasmarton commented Oct 6, 2017

Choose a reason for hiding this comment