Add a bit of documentation

Change-Id: Ie202c072ab10783c4030af280023795e498d2523

1 files changed, 16 insertions, 5 deletions

diff --git a/include/comphelper/lok.hxx b/include/comphelper/lok.hxx
index ba4745c8e61b..704fb1f65193 100644
--- a/include/comphelper/lok.hxx
+++ b/include/comphelper/lok.hxx
@@ -1,4 +1,4 @@
-/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4; fill-column: 100 -*- */
 /*
  * This file is part of the LibreOffice project.
  *
@@ -12,24 +12,35 @@
 
 #include <comphelper/comphelperdllapi.h>
 
+// Interface between the LibreOfficeKit implementation called by LibreOfficeKit clients and other
+// LibreOffice code.
+
 namespace comphelper
 {
 
 namespace LibreOfficeKit
 {
 
-COMPHELPER_DLLPUBLIC void setActive();
+// Functions to be called only from the LibreOfficeKit implementation in desktop, not from other
+// places in LibreOffice code.
 
-COMPHELPER_DLLPUBLIC bool isActive();
+COMPHELPER_DLLPUBLIC void setActive();
 
 enum class statusIndicatorCallbackType { Start, SetValue, Finish };
 
 COMPHELPER_DLLPUBLIC void setStatusIndicatorCallback(void (*callback)(void *data, statusIndicatorCallbackType type, int percent), void *data);
 
-COMPHELPER_DLLPUBLIC void statusIndicatorStart();
 
-COMPHELPER_DLLPUBLIC void statusIndicatorSetValue(int percent);
+// Functions that can be called from arbitrary places in LibreOffice.
+
+// Check whether the code is running as invoked through LibreOfficeKit.
+COMPHELPER_DLLPUBLIC bool isActive();
 
+// Status indicator handling. Even if in theory there could be several status indicators active at
+// the same time, in practice there is only one at a time, so we don't handle any identification of
+// status indicator in this API.
+COMPHELPER_DLLPUBLIC void statusIndicatorStart();
+COMPHELPER_DLLPUBLIC void statusIndicatorSetValue(int percent);
 COMPHELPER_DLLPUBLIC void statusIndicatorFinish();
 
 }