Feature/doxygen #383

simonnagl · 2016-05-06T11:52:12Z

Added doxygen-style documentation to proc_self_mountinfo.h
This should not be merged as is.

Things to be done before we can merge this:

Include generation of the doc to into the build process.
Document at least all header files.

To view the documentation these steps are needed:

Change dir to project root.
doxygen doxygen.conf
View doc/html/index.html to see the documentation of the file.

simonnagl · 2017-01-11T10:56:46Z

Commented appconfig.h. @ktsaou Please tell me if you like this kind of documentation. If you like it I would document all the header files like this. I think this makes a enormous step in code quality and can help new contributors.

If you like it also comment if I made some mistakes and comment the lines I requested your help. Also tell me if you think it is to much work for the benefit.

ktsaou · 2017-01-11T18:09:29Z

@simonnagl nice work.

Include generation of the doc to into the build process.

Keep in mind I would like this to be opt-in, not opt-out.

simonnagl · 2017-01-11T18:17:25Z

I have added comments to commit beb13dc

I have read them and updated the comments. Thank you for that

Keep in mind I would like this to be opt-in, not opt-out.

This was my intention too.

ktsaou · 2017-01-11T18:18:29Z

perfect!

simonnagl · 2017-01-13T09:52:32Z

Documented avl.h. @ktsaou There I also need your help. Do you want me to always notify you if there is something new your help is requested or do you want to get it bundled after I finished all header files.

Now doxygen is included into the build chain. The Output format of doxygen can be configured. For example --disable-doxygen-pdf for a complete list run ./configure --help

There are some new make targets:

doxygen-doc: Generate all doxygen documentation.
doxygen-run: Run doxygen, which will generate some of the documentation (HTML, CHM, CHI, MAN, RTF, XML) but will not do the post processing required for the rest of it (PS, PDF).
doxygen-ps: Generate doxygen PostScript documentation.
doxygen-pdf: Generate doxygen PDF documentation.

Now there is one question to discuss. Do we want to add an option --generate-doxygen to the netdata installer? Where should we document this feature?

ktsaou · 2017-01-13T18:55:23Z

.gitignore

@@ -83,6 +83,7 @@ CMakeFiles/
 cmake_install.cmake

 .jetbrains*
+<<<<<<< HEAD


ktsaou · 2017-01-14T16:11:21Z

sorry.. I broke this...

simonnagl · 2017-01-14T16:52:24Z

No problem. Rebased to master. Your doing real good work!

simonnagl · 2017-01-16T12:36:26Z

@ktsaou Added some new TODO's where I need your help...

ktsaou · 2017-01-16T21:04:45Z

src/avl.h

 void avl_init(avl_tree *t, int (*compar)(void *a, void *b));

-
+/**
+ * \todo kstou Your help needed.


walk through all entries in the AVL tree. The function int callback(entry, data) will be called for each node (data is the data parameter to the traverse function).

The return value of callback() is interpreted as follows:

zero, or positive = add it to total.

negative = stop traversing the tree.

If no call to callback returns a negative number, the return value of the traverse function is the total.
If any call to callback returns a negative number, the return value is the number returned by that callback function.

I have never verified, if this calls the callback function in a sorted order (I hope it does, but I never really cared since netdata uses these AVL trees with string hashes - so sorting them based on the hashes is meaningless).

The lock version, locks the tree for the entire walk through (so use it with care).

ktsaou · 2017-01-16T21:06:50Z

src/clocks.h

+ * 
+ * @see man 2 gettimeofday
+ *
+ * @param clk_id Not used. \todo Should we change API here?


this is work in progress. There is PR #1368 with more changes.

ktsaou · 2017-01-16T21:07:32Z

src/main.h

+ *
+ * \section sec_outline Outline
+ *
+ * \todo 


This comment block starts with \mainpage.

This will be the initial start page of doxygen. I am not shure anymore if this is the right place to put it because your question mark. The todo is for me.

I think on the homepage of the doxygen documentation we should give an overview where to find wich part of net data. Also there should be additional information about coding rules etc. (Things the user of netdata does not need to no but the contributor)

What do you think?

ktsaou · 2017-01-16T21:11:52Z

src/common.h

 extern void strreverse(char* begin, char* end);
+/**
+ * \todo ktsaou, can you please explain whats different to strsep here?


like strsep() but it automatically skips adjusting delimiters (so if the delimiter is a space, it will will skip all spaces).

ktsaou · 2017-01-16T21:14:56Z

src/common.h

 extern void freez(void *ptr);
 #endif

+/**
+ * \todo ktsaou: your help needed. Especially when this should be used.


When a string is to be added to a JSON object, we need to escape it (i.e. escape double quotes and backslashes). It is like strncpy(), but it escapes the string while copying it.

ktsaou · 2017-01-16T21:21:02Z

src/common.h

 extern void json_escape_string(char *dst, const char *src, size_t size);

+/**
+ * \todo ktsaou: your help needed. Especially what is the difference to mmap 


it creates the file if does not exist (to the correct size).

it truncates the file if it already exists and is bigger than expected.

sets various memory management heuristics we know netdata memory databases use (like MADV_SEQUENTIAL)

prevents this memory from being copied when netdata forks to execute its plugins.

enables KSM for it.

in memory mode ram, it loads the file into memory (in all other modes, loading it is on-demand by the kernel).

ktsaou · 2017-01-16T21:24:28Z

src/common.h

 extern int read_single_number_file(const char *filename, unsigned long long *result);

+/// \todo ktsaou: your help needed


haha... this is old... you need to fetch the latest.

To understand simple patterns, check this #1571 (comment)

You can run netdata -W simple-pattern for more help or to play with it...

The general rule is:

The create call builds a linked list (more like a tree) of substrings to be matched, each matched as PREFIX, SUFFIX, SUBSTRING or EXACT.

The match call checks a string against a pattern that has been parsed with create.

The free call frees the memory allocated by create.

The whole mechanism supports both positive and negative matches.

haha... this is old... you need to fetch the latest

This is in the current master... Did I understand you wrong?

ktsaou · 2017-01-16T21:28:57Z

src/common.h

+    NETDATA_SIMPLE_PATTERN_MODE_SUFFIX,   ///< \todo ktsaou: your help needed
+    NETDATA_SIMPLE_PATTERN_MODE_SUBSTRING ///< \todo ktsaou: your help needed
+} NETDATA_SIMPLE_PREFIX_MODE;
+typedef void NETDATA_SIMPLE_PATTERN; ///< \todo ktsaou: you help needed


This is a way to prevent exposing the internals of simple patterns to the rest of netdata. So, all the calls accept SIMPLE_PATTERN *, which is actually a void *.

ktsaou · 2017-01-16T21:29:50Z

I think I answered all. If you find any missing, please let me know.
You need to update your repo...

simonnagl

Thank you for helping out. I removed @ktsaou from the commit message.

simonnagl · 2017-01-17T07:07:27Z

src/main.h

+ *
+ * \section sec_outline Outline
+ *
+ * \todo 


This comment block starts with \mainpage.

This will be the initial start page of doxygen. I am not shure anymore if this is the right place to put it because your question mark. The todo is for me.

I think on the homepage of the doxygen documentation we should give an overview where to find wich part of net data. Also there should be additional information about coding rules etc. (Things the user of netdata does not need to no but the contributor)

What do you think?

simonnagl · 2017-01-17T07:29:33Z

src/common.h

 extern int read_single_number_file(const char *filename, unsigned long long *result);

+/// \todo ktsaou: your help needed


haha... this is old... you need to fetch the latest

This is in the current master... Did I understand you wrong?

ktsaou · 2017-01-17T07:51:36Z

ok. sounds nice.

simonnagl · 2017-01-17T10:14:41Z

I went on and documented all structs.

@ktsaou There are some TODOs I nee your help.

ktsaou · 2017-01-17T19:13:29Z

src/global_statistics.h

+    volatile uint16_t connected_clients; ///< number of connected clients
+
+    volatile uint64_t web_requests;            ///< Number of web requests.
+    volatile uint64_t web_usec;                ///< ktsaou: Your help needed


sum of the duration to serve web_requests (from the reception of the request, to the dispatch of the last byte).

ktsaou · 2017-01-17T19:14:16Z

src/global_statistics.h

+
+    volatile uint64_t web_requests;            ///< Number of web requests.
+    volatile uint64_t web_usec;                ///< ktsaou: Your help needed
+    volatile uint64_t web_usec_max;            ///< ktsaou: Your help needed


the max time to serve a request. This is reset to zero every time the chart is updated, so it shows the max time for each iteration.

simonnagl · 2017-02-18T07:49:36Z

src/registry_internals.h

+/**
+ * ktsaou: Your help needed.
+ *
+ * @return ktsaou: Your help needed.


I understand that log is something like a DB. Can you please clarify what's the difference between registry_log_load and registry_db_load?

of course.

registry_db is a dump of the registry database in memory.
registry_log is the transaction log, that alters the database in memory.

So, for a variable X in the database that is updated 10 times, you will have 10 rows in registry_log immediately after the value is changed.

When 1.000.000 (configurable) rows are written to registry_log, the database is dumped again in registry_db and registry_log is rotated.

This way, even if netdata crashes, transactions are not lost. When netdata starts, it loads registry_db and then registry_log, to continue from the point it was.

simonnagl · 2017-02-18T07:53:46Z

src/rrd.h


-typedef long long total_number;
-#define TOTAL_NUMBER_FORMAT "%lld"
+typedef long long total_number;    ///< ktsaou: Your help needed.


@ktsaou Your help needed.

simonnagl · 2017-02-18T08:03:08Z

src/rrd.h

 extern RRDSET *rrdset_find_byname(const char *name);

+/**
+ * ktsaou: Your help needed.


@ktsaou Your help needed.

simonnagl · 2017-02-19T11:23:07Z

src/rrd.h

+/**
+ * ktsaou: Your help needed.
+ *
+ * @param st RRDSET.


@ktsaou Your help needed

simonnagl · 2017-02-19T11:23:25Z

src/rrd.h

 extern void rrdset_next_usec(RRDSET *st, usec_t microseconds);
+/**
+ * ktsaou: Your help needed.


@ktsaou Your help needed

simonnagl · 2017-02-19T11:27:25Z

src/rrd.h

+ * @param st RRDSET of RRDDIM.
+ * @param rd RRDDIM.
+ * @param value to add.
+ * @return ktsaou: Your help needed. Last interpolated value?


@ktsaou: Your help needed

simonnagl · 2017-02-19T11:28:46Z

src/rrd2json.h

+#define GROUP_MIN 2             ///< (a,b) => a>b?b:a
+#define GROUP_MAX 3             ///< (a,b) => a>b?a:b
+#define GROUP_SUM 4             ///< (a,b) => a+b
+#define GROUP_INCREMENTAL_SUM 5 ///< ktsaou: Your help needed.


@ktsaou: Your help needed.

simonnagl · 2017-02-21T16:09:46Z

src/unit_test.h

+/**
+ * Run all unit tests.
+ *
+ * @param delay ktsaou: Your help needed


@ktsaou: Your help needed

simonnagl · 2017-02-21T16:10:14Z

src/unit_test.h

+ * Run all unit tests.
+ *
+ * @param delay ktsaou: Your help needed
+ * @param shift kstaou: Your help needed


@ktsaou: Your help

ktsaou · 2017-02-22T23:09:15Z

@simonnagl I know you wait for me. I need to focus on multi-host support (which unfortunately will break a lot of your changes - sorry...). Give me a few days to finish it.

simonnagl · 2017-02-24T07:58:28Z

No problem!

simonnagl · 2017-03-01T10:22:01Z

I see many many changes. I'll start rebasing now. I do not know if I can finish this soon.
When I adapted the changes to current master I will notify you.

If you agree even if there are some points left I would like you to merge this. There won't be wrong documentation but missing one. I will change to TODOs instead of ktsaou: Your help needed. These can be done in feature merge requests then.

We can discuss this if it is mergeable again.

paulfantom · 2018-10-20T16:37:16Z

@cakrit look at this.

simonnagl · 2018-12-25T23:02:13Z

@cakrit If you are interested in this I can adopt this PR for the new directory structure. Just tell me.

cakrit · 2018-12-26T20:33:52Z

Thanks @simonnagl. Although I won't be able to look into this in the short term, you're probably right and it won't be possible to proceed at all if it's not adapted to the new structure. I'd be a bit hesitant to take up your time before we've decided to proceed with this though. We'll have a new dev joining in Jan, so I'll discuss it with him first.

simonnagl · 2019-02-08T06:52:02Z

I will close this for now. If you want to have this in Netdata please contact me. I am willing to provide a setup with the basic work again.

simonnagl force-pushed the feature/doxygen branch from 21f27c4 to beb13dc Compare January 11, 2017 10:52

simonnagl force-pushed the feature/doxygen branch from beb13dc to 02ecc06 Compare January 11, 2017 12:06

simonnagl force-pushed the feature/doxygen branch from a28020c to b868129 Compare January 13, 2017 07:22

simonnagl force-pushed the feature/doxygen branch from 0e6e1da to 1756eb4 Compare January 13, 2017 12:35

ktsaou reviewed Jan 13, 2017

View reviewed changes

.gitignore Outdated

@@ -83,6 +83,7 @@ CMakeFiles/

cmake_install.cmake

.jetbrains*

<<<<<<< HEAD

Copy link

Member

ktsaou Jan 13, 2017

Choose a reason for hiding this comment

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

oops!

simonnagl force-pushed the feature/doxygen branch from 28735e6 to 672e6f4 Compare January 14, 2017 16:51

simonnagl force-pushed the feature/doxygen branch from 672e6f4 to 97b8acf Compare January 16, 2017 12:35

ktsaou reviewed Jan 16, 2017

View reviewed changes

simonnagl commented Jan 17, 2017

View reviewed changes

simonnagl force-pushed the feature/doxygen branch from 97b8acf to 962479c Compare January 17, 2017 07:31

ktsaou reviewed Jan 17, 2017

View reviewed changes

simonnagl force-pushed the feature/doxygen branch from 60a2a12 to c8abeeb Compare February 17, 2017 21:07

simonnagl commented Feb 18, 2017

View reviewed changes

src/rrd.h

extern RRDSET *rrdset_find_byname(const char *name);

/**

* ktsaou: Your help needed.

Copy link

Author

simonnagl Feb 18, 2017

Choose a reason for hiding this comment

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

@ktsaou Your help needed.

simonnagl commented Feb 19, 2017

View reviewed changes

src/rrd.h

/**

* ktsaou: Your help needed.

*

* @param st RRDSET.

Copy link

Author

simonnagl Feb 19, 2017

Choose a reason for hiding this comment

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

@ktsaou Your help needed

simonnagl commented Feb 19, 2017

View reviewed changes

src/rrd.h

extern void rrdset_next_usec(RRDSET *st, usec_t microseconds);

/**

* ktsaou: Your help needed.

Copy link

Author

simonnagl Feb 19, 2017

Choose a reason for hiding this comment

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

@ktsaou Your help needed

simonnagl commented Feb 19, 2017

View reviewed changes

simonnagl commented Feb 21, 2017

View reviewed changes

src/unit_test.h

/**

* Run all unit tests.

*

* @param delay ktsaou: Your help needed

Copy link

Author

simonnagl Feb 21, 2017

Choose a reason for hiding this comment

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

@ktsaou: Your help needed

simonnagl commented Feb 21, 2017

View reviewed changes

paulfantom added the area/docs label Oct 20, 2018

cakrit self-assigned this Oct 23, 2018

paulfantom force-pushed the master branch 8 times, most recently from 9134341 to 70de864 Compare November 2, 2018 13:12

paulfantom added the no changelog Issues which are not going to be added to changelog label Dec 4, 2018

simonnagl closed this Feb 8, 2019

simonnagl deleted the feature/doxygen branch November 19, 2019 13:25

		extern int read_single_number_file(const char filename, unsigned long long result);

		/// \todo ktsaou: your help needed

Feature/doxygen #383

Feature/doxygen #383

Conversation

simonnagl commented May 6, 2016 • edited

simonnagl commented Jan 11, 2017

ktsaou commented Jan 11, 2017

simonnagl commented Jan 11, 2017 • edited

ktsaou commented Jan 11, 2017

simonnagl commented Jan 13, 2017

Choose a reason for hiding this comment

ktsaou commented Jan 14, 2017

simonnagl commented Jan 14, 2017

simonnagl commented Jan 16, 2017

ktsaou Jan 16, 2017 • edited

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

ktsaou commented Jan 16, 2017

simonnagl left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ktsaou commented Jan 17, 2017

simonnagl commented Jan 17, 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

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

ktsaou commented Feb 22, 2017

simonnagl commented Feb 24, 2017

simonnagl commented Mar 1, 2017

paulfantom commented Oct 20, 2018

simonnagl commented Dec 25, 2018

cakrit commented Dec 26, 2018

simonnagl commented Feb 8, 2019

simonnagl commented May 6, 2016 •

edited

simonnagl commented Jan 11, 2017 •

edited

ktsaou Jan 16, 2017 •

edited