Improve views/viewers documentation

2 files changed, 22 insertions, 3 deletions

diff --git a/server/lib/views/shared/video-viewers.ts b/server/lib/views/shared/video-viewers.ts
index 5c26f8982..4dad1f0e8 100644
--- a/server/lib/views/shared/video-viewers.ts
+++ b/server/lib/views/shared/video-viewers.ts
@@ -41,7 +41,7 @@ export class VideoViewers {
   private processingViewerStats = false
 
   constructor () {
-    setInterval(() => this.cleanViewerCounters(), VIEW_LIFETIME.VIEWER)
+    setInterval(() => this.cleanViewerCounters(), VIEW_LIFETIME.VIEWER_COUNTER)
 
     setInterval(() => this.processViewerStats(), VIEW_LIFETIME.VIEWER_STATS)
   }
@@ -56,7 +56,7 @@ export class VideoViewers {
   }
 
   buildViewerExpireTime () {
-    return new Date().getTime() + VIEW_LIFETIME.VIEWER
+    return new Date().getTime() + VIEW_LIFETIME.VIEWER_COUNTER
   }
 
   async getWatchTime (videoId: number, ip: string) {
@@ -210,7 +210,7 @@ export class VideoViewers {
     if (this.processingViewerStats) return
     this.processingViewerStats = true
 
-    if (!isTestInstance()) logger.info('Processing viewers.', lTags())
+    if (!isTestInstance()) logger.info('Processing viewer statistics.', lTags())
 
     const now = new Date().getTime()
 
@@ -220,6 +220,7 @@ export class VideoViewers {
       for (const key of allKeys) {
         const stats: LocalViewerStats = await Redis.Instance.getLocalVideoViewer({ key })
 
+        // Process expired stats
         if (stats.lastUpdated > now - VIEW_LIFETIME.VIEWER_STATS) {
           continue
         }
diff --git a/server/lib/views/video-views-manager.ts b/server/lib/views/video-views-manager.ts
index e07af1ca9..9382fb482 100644
--- a/server/lib/views/video-views-manager.ts
+++ b/server/lib/views/video-views-manager.ts
@@ -3,6 +3,24 @@ import { MVideo } from '@server/types/models'
 import { VideoViewEvent } from '@shared/models'
 import { VideoViewers, VideoViews } from './shared'
 
+/**
+ * If processing a local view:
+ *  - We update viewer information (segments watched, watch time etc)
+ *  - We add +1 to video viewers counter if this is a new viewer
+ *  - We add +1 to video views counter if this is a new view and if the user watched enough seconds
+ *  - We send AP message to notify about this viewer and this view
+ *  - We update last video time for the user if authenticated
+ *
+ * If processing a remote view:
+ *  - We add +1 to video viewers counter
+ *  - We add +1 to video views counter
+ *
+ * A viewer is a someone that watched one or multiple sections of a video
+ * A viewer that watched only a few seconds of a video may not increment the video views counter
+ * Viewers statistics are sent to origin instance using the `WatchAction` ActivityPub object
+ *
+ */
+
 const lTags = loggerTagsFactory('views')
 
 export class VideoViewsManager {