Added documentation for generated files #1494

ethouris · 2020-08-20T09:41:40Z

No description provided.

docs/Developers.md

Co-authored-by: stevomatthews <smatthews@haivision.com>

stevomatthews · 2020-08-21T14:21:15Z

docs/Developers.md

+The fine-grained functional areas in the logging system allows the developer to
+turn on selectively only some smaller areas so that the logging doesn't overflow
+the performance and change the behavior when testing, in case when heavy debug
+logging is turned on.


Suggested change

The fine-grained functional areas in the logging system allows the developer to

turn on selectively only some smaller areas so that the logging doesn't overflow

the performance and change the behavior when testing, in case when heavy debug

logging is turned on.

The fine-grained functional structure of the logging system allows a developer to

selectively turn on only specific areas. This is useful during testing to help minimize the impact of logging on performance or behavior.

"functional area" term should remain used here. Maybe it should be phrased in the sentence a little different.

How about:
"The logging system has functional areas (FA) that allow a developer to
selectively turn on only specific types of logs. This is ..."

Ok, still not sure that this sounds clear.

The logging system has two aspects for every log, which is level and FA. Every logging instruction looks more-less like this:

LOGC(cclog.Note, log << "Here is the note");

where:
cclog - the logger variable that defines the FA. Here cc means "Congestion Control".
Note - the log level, one of: Debug, Note, Warn, Error, Fatal.

By setting the log level, you allow only logs of given level and above to be printed. By seting on/off particular FA, you allow logs only for allowed FA to be printed.

Your version seems to be clear enough, though. I'll try to add only some more information to this sentence to clarify.

How about:
"In addition to levels (Debug, Note, Warn, Error, Fatal) the logging system has functional areas (FA) that allow a developer to
selectively turn on only specific types of logs. For example, in this logging instruction:

LOGC(cclog.Note, log << "Here is the note");

cclog is a logger variable that defines the FA (Congestion Control). And Note defines the log level. By setting an FA, you allow logs only for that FA to be printed. By setting the log level, you allow only logs of that level and above to be printed. This is ..."

Ok, I've tried to make some common version out of it all. Please re-check.

docs/Developers.md

Co-authored-by: stevomatthews <smatthews@haivision.com>

stevomatthews · 2020-08-21T15:16:31Z

docs/Developers.md

+* Note that `srt.inc.h` file generates only a part that you have to place in srt.h
+   * Find any `SRT_LOGFA_` symbol to find the place where it should be pasted


Suggested change

* Note that `srt.inc.h` file generates only a part that you have to place in srt.h

* Find any `SRT_LOGFA_` symbol to find the place where it should be pasted

* The script generates `srt.inc.h` with the parts you have added or changed (e.g. `#define SRT_LOGFA_GENERAL 0 // glog`)

* Copy any new definitions from `srt.inc.h` into `srt.h` at the appropriate place (search for `SRT_LOGFA_`)

Not sure if this makes it clearer. The srt.inc.h file is not really a part of generated files - this exceptionally contains only a "generated part" that shouild be pasted into srt.h file. The 3 others are fully generated files.

Could you please show where to find srt.inc.h? It will help me to understand better.

Tell you what. Forget it. I decided to change things here. Now all files will be generated.

stevomatthews · 2020-08-21T15:20:48Z

docs/Developers.md

+* entry format for `hidden_loggers` (optional)
+
+The 'format model' uses two variables: `globalheader`, which is the obligatory
+header for all source files, and `entries` in a place where the list of FA entries


What is "FA"?

Functional Area.

stevomatthews · 2020-08-21T15:21:28Z

docs/Developers.md

+
+If you modify the `CMakeLists.txt` file and add some build options to it, remember to
+generate this list of options and update appropriately the `configure-data.tcl` file.
+This file requires to be run in the build directory and passed the `CMakeCache.txt`


Suggested change

This file requires to be run in the build directory and passed the `CMakeCache.txt`

This file must be run in the build directory and passed the `CMakeCache.txt`

stevomatthews · 2020-08-21T15:24:09Z

docs/Developers.md

+Note that it doesn't mean that the contents should be blindly pasted into the
+options list, just apply only these new options that you have added - this
+script does its best to make sure that no option is missing, but some of them
+could be provided by some foreign dependent script (like `build-gmock`) and
+therefore they are mistakenly added to the list.


Suggested change

Note that it doesn't mean that the contents should be blindly pasted into the

options list, just apply only these new options that you have added - this

script does its best to make sure that no option is missing, but some of them

could be provided by some foreign dependent script (like `build-gmock`) and

therefore they are mistakenly added to the list.

Note that this does not mean that the contents should be blindly pasted into the

options list. Apply only the new options that you have added. The

script does its best to make sure that no option is missing. Note that some options might be provided by an external dependent script (like `build-gmock`) and

therefore mistakenly added to the list.

stevomatthews

Minor edits.

stevomatthews · 2020-08-21T17:33:24Z

docs/Developers.md

+* entry format for `hidden_loggers` (optional)
+
+The 'format model' uses two variables: `globalheader`, which is the obligatory
+header for all source files, and `entries` in a place where the list of FA entries


Suggested change

header for all source files, and `entries` in a place where the list of FA entries

header for all source files, and `entries` in a place where the list of functional area (FA) entries

stevomatthews

Minor edit

stevomatthews

All good.

docs/Developers.md

Co-authored-by: Maxim Sharabayko <maxlovic@gmail.com>

Added documentation for generated files

6bf0298

ethouris requested review from maxsharabayko and stevomatthews August 20, 2020 09:41

ethouris self-assigned this Aug 20, 2020

ethouris added [docs] Area: Improvements or additions to documentation Impact: Development Priority: High Type: Maintenance Work required to maintain or clean up the code labels Aug 20, 2020

ethouris added this to the v1.5.0 - Sprint 21 milestone Aug 20, 2020

ethouris pushed a commit to ethouris/srt that referenced this pull request Aug 20, 2020

Withdrawn docs changes, moved to another PR: Haivision#1494

eea189b

stevomatthews reviewed Aug 21, 2020

View reviewed changes

docs/Developers.md Outdated Show resolved Hide resolved

Followup: docs/Developers.md

d733ba9

Co-authored-by: stevomatthews <smatthews@haivision.com>

stevomatthews reviewed Aug 21, 2020

View reviewed changes

docs/Developers.md Outdated Show resolved Hide resolved

stevomatthews reviewed Aug 21, 2020

View reviewed changes

docs/Developers.md Outdated Show resolved Hide resolved

Apply suggestions from code review

8925b49

Co-authored-by: stevomatthews <smatthews@haivision.com>

stevomatthews reviewed Aug 21, 2020

View reviewed changes

Followup

953f78e

stevomatthews reviewed Aug 24, 2020

View reviewed changes

Mikołaj Małecki added 2 commits August 24, 2020 17:36

Some more fixes for clarity

f914223

Removed mistakenly left old text

b5a7909

maxsharabayko modified the milestones: v1.5.0 - Sprint 21, v1.5.0 - Sprint 22 Aug 25, 2020

mbakholdina assigned maxsharabayko Aug 26, 2020

mbakholdina removed the Impact: Development label Aug 26, 2020

stevomatthews approved these changes Aug 27, 2020

View reviewed changes

maxsharabayko requested changes Aug 27, 2020

View reviewed changes

docs/Developers.md Outdated Show resolved Hide resolved

docs/Developers.md Outdated Show resolved Hide resolved

Apply suggestions from code review (consistency)

8b23ccf

Co-authored-by: Maxim Sharabayko <maxlovic@gmail.com>

maxsharabayko approved these changes Aug 31, 2020

View reviewed changes

maxsharabayko merged commit a755d8f into Haivision:master Aug 31, 2020

mbakholdina modified the milestones: v1.5.0 - Sprint 22, v1.4.2 Oct 14, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added documentation for generated files #1494

Added documentation for generated files #1494

ethouris commented Aug 20, 2020

stevomatthews Aug 21, 2020

ethouris Aug 21, 2020

stevomatthews Aug 21, 2020 •

edited

Loading

ethouris Aug 24, 2020

ethouris Aug 24, 2020

stevomatthews Aug 24, 2020

ethouris Aug 24, 2020

stevomatthews Aug 21, 2020

ethouris Aug 21, 2020

stevomatthews Aug 21, 2020

ethouris Aug 24, 2020

stevomatthews Aug 21, 2020

ethouris Aug 21, 2020

stevomatthews Aug 21, 2020 •

edited

Loading

stevomatthews Aug 21, 2020

stevomatthews left a comment

stevomatthews Aug 21, 2020

stevomatthews left a comment

stevomatthews left a comment

		* Note that `srt.inc.h` file generates only a part that you have to place in srt.h
		* Find any `SRT_LOGFA_` symbol to find the place where it should be pasted

	This file requires to be run in the build directory and passed the `CMakeCache.txt`
	This file must be run in the build directory and passed the `CMakeCache.txt`

	header for all source files, and `entries` in a place where the list of FA entries
	header for all source files, and `entries` in a place where the list of functional area (FA) entries

Added documentation for generated files #1494

Added documentation for generated files #1494

Conversation

ethouris commented Aug 20, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stevomatthews Aug 21, 2020 • edited Loading

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

stevomatthews Aug 21, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stevomatthews left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stevomatthews left a comment

Choose a reason for hiding this comment

stevomatthews left a comment

Choose a reason for hiding this comment

stevomatthews Aug 21, 2020 •

edited

Loading

stevomatthews Aug 21, 2020 •

edited

Loading