Add comments to javascript

Author: Archmonger

src/js/src/index.js

@@ -12,9 +12,19 @@ export function bind(node) {
   };
 }
 
+/**
+ * History component that captures browser "history go back" actions and notifies the server.
+ *
+ * @param {Object} props - The properties object.
+ * @param {Function} props.onHistoryChangeCallback - Callback function to notify the server about history changes.
+ * @returns {null} This component does not render any visible output.
+ * @description
+ * This component uses the `popstate` event to detect when the user navigates back in the browser history.
+ * It then calls the `onHistoryChangeCallback` with the current pathname and search parameters.
+ * Note: Browsers do not allow detection of "history go forward" actions.
+ * @see https://github.com/reactive-python/reactpy/pull/1224
+ */
 export function History({ onHistoryChangeCallback }) {
-  // Capture browser "history go back" action and tell the server about it
-  // Note: Browsers do not allow us to detect "history go forward" actions.
   React.useEffect(() => {
     // Register a listener for the "popstate" event and send data back to the server using the `onHistoryChange` callback.
     const listener = () => {
@@ -32,8 +42,10 @@ export function History({ onHistoryChangeCallback }) {
   });
 
   // Tell the server about the URL during the initial page load
-  // FIXME: This currently runs every time any component is mounted due to a ReactPy core rendering bug.
+  // FIXME: This code is commented out since it currently runs every time any component
+  // is mounted due to a ReactPy core rendering bug.
   // https://github.com/reactive-python/reactpy/pull/1224
+
   // React.useEffect(() => {
   //   onHistoryChange({
   //     pathname: window.location.pathname,
@@ -44,10 +56,20 @@ export function History({ onHistoryChangeCallback }) {
   return null;
 }
 
-// FIXME: The Link component is unused due to a ReactPy core rendering bug
-// which causes duplicate rendering (and thus duplicate event listeners).
-// https://github.com/reactive-python/reactpy/pull/1224
+
+/**
+ * Link component that captures clicks on anchor links and notifies the server.
+ *
+ * @param {Object} props - The properties object.
+ * @param {Function} props.onClickCallback - Callback function to notify the server about link clicks.
+ * @param {string} props.linkClass - The class name of the anchor link.
+ * @returns {null} This component does not render any visible output.
+ */
 export function Link({ onClickCallback, linkClass }) {
+  // FIXME: This component is currently unused due to a ReactPy core rendering bug
+  // which causes duplicate rendering (and thus duplicate event listeners).
+  // https://github.com/reactive-python/reactpy/pull/1224
+
   // This component is not the actual anchor link.
   // It is an event listener for the link component created by ReactPy.
   React.useEffect(() => {
@@ -79,6 +101,15 @@ export function Link({ onClickCallback, linkClass }) {
   return null;
 }
 
+/**
+ * Client-side portion of the navigate component, that allows the server to command the client to change URLs.
+ *
+ * @param {Object} props - The properties object.
+ * @param {Function} props.onNavigateCallback - Callback function that transmits data to the server.
+ * @param {string} props.to - The target URL to navigate to.
+ * @param {boolean} props.replace - If true, replaces the current history entry instead of adding a new one.
+ * @returns {null} This component does not render anything.
+ */
 export function Navigate({ onNavigateCallback, to, replace }) {
   React.useEffect(() => {
     if (replace) {