Add a bit of documentation

Change-Id: Ie202c072ab10783c4030af280023795e498d2523

include/comphelper/lok.hxx

-/* -*- 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();
 
 }