Merge pull request #491 from GatherPress/mauteri-document

Document all code.

includes/core/classes/class-event.php

@@ -930,10 +930,22 @@ function( $key ) {
 	public function maybe_get_online_event_link(): string {
 		$event_link = (string) get_post_meta( $this->event->ID, '_online_event_link', true );
 
-		if (
-			! apply_filters( 'gatherpress_force_online_event_link', false ) &&
-			! is_admin()
-		) {
+		/**
+		 * Filters whether to force the display of the online event link.
+		 *
+		 * Allows modification of the decision to force the online event link
+		 * display in the `maybe_get_online_event_link` method. Return true to
+		 * force the online event link, or false to allow normal checks.
+		 *
+		 * @since 1.0.0
+		 *
+		 * @param bool $force_online_event_link Whether to force the display of the online event link.
+		 *
+		 * @return bool True to force online event link, false to allow normal checks.
+		 */
+		$force_online_event_link = apply_filters( 'gatherpress_force_online_event_link', false );
+
+		if ( ! $force_online_event_link && ! is_admin() ) {
 			if ( ! $this->rsvp ) {
 				return '';
 			}

includes/core/classes/class-settings.php

@@ -537,6 +537,18 @@ public function get_name_field( string $sub_page, string $section, string $optio
 	 * @return array An array of sub-pages, each with settings and priority information.
 	 */
 	public function get_sub_pages(): array {
+		/**
+		 * Filters the list of GatherPress sub pages.
+		 *
+		 * Allows a companion plugin or theme to extend GatherPress settings
+		 * by adding additional sub pages to the settings page.
+		 *
+		 * @since 1.0.0
+		 *
+		 * @param array $sub_pages The array of sub pages.
+		 *
+		 * @return array Modified array of sub pages.
+		 */
 		$sub_pages = (array) apply_filters( 'gatherpress_sub_pages', array() );
 
 		uasort( $sub_pages, array( $this, 'sort_sub_pages_by_priority' ) );

includes/core/classes/settings/class-leadership.php

@@ -79,11 +79,25 @@ protected function get_sections(): array {
 			),
 		);
 
+		/**
+		 * Filter the list of roles for GatherPress.
+		 *
+		 * This filter allows modification of the list of user roles used by GatherPress.
+		 * By default, GatherPress supports only the 'Organizers' role.
+		 *
+		 * @since 1.0.0
+		 *
+		 * @param array $roles An array of user roles supported by GatherPress.
+		 *                     By default, it includes only the 'Organizers' role.
+		 * @return array The modified array of user roles.
+		 */
+		$roles = apply_filters( 'gatherpress_roles', $roles );
+
 		return array(
 			'roles' => array(
 				'name'        => __( 'Roles', 'gatherpress' ),
 				'description' => __( 'Customize role labels to be more appropriate for events.', 'gatherpress' ),
-				'options'     => apply_filters( 'gatherpress_roles', $roles ),
+				'options'     => $roles,
 			),
 		);
 	}

src/admin.js

@@ -10,12 +10,24 @@ import { getBlockType, unregisterBlockType } from '@wordpress/blocks';
 import { getFromGlobal } from './helpers/globals';
 
 /**
- * Remove unwanted blocks from localized array.
+ * Remove Unwanted Blocks
+ *
+ * This script removes unwanted blocks from the localized array.
+ * It utilizes the `domReady` function to ensure the DOM is ready before execution.
+ * It iterates through the keys of the 'unregister_blocks' array obtained from the global scope,
+ * retrieves the block name, and unregisters the block using the `unregisterBlockType` function.
+ *
+ * @since 1.0.0
  */
+
+// Execute the following code when the DOM is ready.
 domReady(() => {
+	// Iterate through keys of the 'unregister_blocks' array in the global scope.
 	Object.keys(getFromGlobal('unregister_blocks')).forEach((key) => {
+		// Retrieve the block name using the key.
 		const blockName = getFromGlobal('unregister_blocks')[key];
 
+		// Check if the block name is defined and unregister the block.
 		if (blockName && 'undefined' !== typeof getBlockType(blockName)) {
 			unregisterBlockType(blockName);
 		}

src/blocks/add-to-calendar/add-to-calendar.js

@@ -24,6 +24,15 @@ const addToCalendarToggle = (e) => {
 
 /**
  * Initialize all Add To Calendar blocks.
+ *
+ * This function initializes the behavior of Add To Calendar blocks on the page.
+ * It sets up event listeners for click and keydown events to toggle the display
+ * of the calendar options list. The function targets elements with the class
+ * 'gp-add-to-calendar' and adds event listeners to handle user interactions.
+ *
+ * @since 1.0.0
+ *
+ * @return {void}
  */
 const addToCalendarInit = () => {
 	const containers = document.querySelectorAll('.gp-add-to-calendar');
@@ -51,6 +60,17 @@ const addToCalendarInit = () => {
 	}
 };
 
+/**
+ * Callback for when the DOM is ready.
+ *
+ * This callback function is executed when the DOM is fully loaded and ready for manipulation.
+ * It calls the `addToCalendarInit` function to initialize the behavior of Add To Calendar blocks
+ * on the page, setting up event listeners for user interactions.
+ *
+ * @since 1.0.0
+ *
+ * @return {void}
+ */
 domReady(() => {
 	addToCalendarInit();
 });

src/blocks/add-to-calendar/edit.js

@@ -10,6 +10,17 @@ import { Flex, FlexItem, Icon } from '@wordpress/components';
  */
 import EditCover from '../../components/EditCover';
 
+/**
+ * Edit component for the GatherPress Add to Calendar block.
+ *
+ * This component renders the edit view of the GatherPress Add to Calendar block.
+ * It provides an interface for users to add the event to their calendar.
+ * The component includes an icon and a link for adding the event to the calendar.
+ *
+ * @since 1.0.0
+ *
+ * @return {JSX.Element} The rendered React component.
+ */
 const Edit = () => {
 	const blockProps = useBlockProps();
 

src/blocks/add-to-calendar/index.js

@@ -7,11 +7,22 @@ import { registerBlockType } from '@wordpress/blocks';
  * Internal dependencies.
  */
 import edit from './edit';
-
 import metadata from './block.json';
-
 import './style.scss';
 
+/**
+ * Register the GatherPress Add to Calendar block.
+ *
+ * This code registers the GatherPress Add to Calendar block in the WordPress block editor.
+ * It utilizes the block metadata from the 'block.json' file and associates it with the
+ * edit component for rendering in the editor. The 'save' function is set to null as
+ * the block doesn't have a front-end representation and is only used in the editor.
+ *
+ * @since 1.0.0
+ *
+ * @return {void}
+ */
+
 registerBlockType(metadata, {
 	edit,
 	save: () => null,

src/blocks/event-date/edit.js

@@ -62,6 +62,25 @@ const displayDateTime = (start, end, tz) => {
 	);
 };
 
+/**
+ * Edit component for the GatherPress Event Date block.
+ *
+ * This component represents the editable view of the GatherPress Event Date block
+ * in the WordPress block editor. It manages the state of date, time, and timezone
+ * for the block and renders the user interface accordingly. The component includes
+ * an icon, displays the formatted date and time, and provides controls to edit the
+ * date and time range via the DateTimeRange component in the InspectorControls.
+ *
+ * @since 1.0.0
+ *
+ * @return {JSX.Element} The rendered Edit component for the GatherPress Event Date block.
+ *
+ * @see {@link DateTimeRange} - Component for editing date and time range.
+ * @see {@link EditCover} - Component for displaying a cover over the block.
+ * @see {@link useBlockProps} - Custom hook for block props.
+ * @see {@link displayDateTime} - Function for formatting and displaying date and time.
+ * @see {@link Listener} - Function for adding event listeners.
+ */
 const Edit = () => {
 	const blockProps = useBlockProps();
 	const [dateTimeStart, setDateTimeStart] = useState(defaultDateTimeStart);

src/blocks/event-date/index.js

@@ -7,11 +7,22 @@ import { registerBlockType } from '@wordpress/blocks';
  * Internal dependencies.
  */
 import edit from './edit';
-
 import metadata from './block.json';
-
 import './style.scss';
 
+/**
+ * Register the GatherPress Event Date block.
+ *
+ * This code registers the GatherPress Event Date block in the WordPress block editor.
+ * It includes metadata from the 'block.json' file, defines the block styles with 'style.scss',
+ * and specifies the 'edit' and 'save' components for the block. The 'edit' component is responsible
+ * for the block's appearance and behavior in the editor, while the 'save' component defines how
+ * the block should be rendered on the front end.
+ *
+ * @since 1.0.0
+ *
+ * @return {void}
+ */
 registerBlockType(metadata, {
 	edit,
 	save: () => null,

src/blocks/events-list/edit.js

@@ -30,6 +30,23 @@ import { useSelect } from '@wordpress/data';
 import EventsList from '../../components/EventsList';
 import EditCover from '../../components/EditCover';
 
+/**
+ * Edit component for the GatherPress Event List block.
+ *
+ * This component renders the edit view of the GatherPress Event List block.
+ * It provides an interface for users to customize the display options of the event list,
+ * including the type of events (upcoming or past), the maximum number of events to display,
+ * topics, venues, and various display options such as showing/hiding RSVP responses,
+ * featured images, descriptions, and event venues.
+ *
+ * @since 1.0.0
+ *
+ * @param {Object}   props               - The properties passed to the component.
+ * @param {Object}   props.attributes    - The block attributes.
+ * @param {Function} props.setAttributes - Function to update block attributes.
+ *
+ * @return {JSX.Element} The rendered React component.
+ */
 const Edit = (props) => {
 	const { attributes, setAttributes } = props;
 	const blockProps = useBlockProps();
@@ -115,6 +132,7 @@ const Edit = (props) => {
 		{ label: 'Thumbnail', value: 'thumbnail' },
 		{ label: 'Large', value: 'large' },
 	];
+
 	return (
 		<>
 			<InspectorControls>

src/blocks/events-list/events-list.js

@@ -9,6 +9,21 @@ import { createRoot } from '@wordpress/element';
  */
 import EventsList from '../../components/EventsList';
 
+/**
+ * Initialize GatherPress Event List blocks.
+ *
+ * This code initializes the GatherPress Event List blocks on the page.
+ * It targets blocks with the data attribute `data-gp_block_name="events-list"`
+ * and initializes the React component `EventsList` with the specified attributes.
+ * If the attributes are not provided, default values are used for customization options.
+ *
+ * @since 1.0.0
+ *
+ * @see {@link EventsList} - React component for rendering the event list.
+ * @see {@link domReady} - Function to execute code when the DOM is ready.
+ *
+ * @return {void}
+ */
 domReady(() => {
 	const containers = document.querySelectorAll(
 		`[data-gp_block_name="events-list"]`

src/blocks/events-list/index.js

@@ -2,15 +2,26 @@
  * External dependencies.
  */
 import { registerBlockType } from '@wordpress/blocks';
+
 /**
  * Internal dependencies.
  */
 import edit from './edit';
-
 import metadata from './block.json';
-
 import './style.scss';
 
+/**
+ * Register the GatherPress Event List block.
+ *
+ * This code registers the GatherPress Event List block in the WordPress block editor.
+ * It uses the block metadata from the 'block.json' file and associates it with the
+ * edit component for rendering in the editor. The 'save' function is set to null as
+ * the block doesn't have a front-end representation and is only used in the editor.
+ *
+ * @since 1.0.0
+ *
+ * @return {void}
+ */
 registerBlockType(metadata, {
 	edit,
 	save: () => null,

src/blocks/online-event/edit.js

@@ -12,6 +12,20 @@ import OnlineEvent from '../../components/OnlineEvent';
 import OnlineEventLink from '../../components/OnlineEventLink';
 import EditCover from '../../components/EditCover';
 
+/**
+ * Edit component for the GatherPress Online Event block.
+ *
+ * This component renders the edit view of the GatherPress Online Event block.
+ * It provides an interface for users to add an online event link.
+ * The component includes an inspector control for managing the online event link.
+ *
+ * @since 1.0.0
+ *
+ * @param {Object}  props            - The component properties.
+ * @param {boolean} props.isSelected - Indicates whether the block is selected.
+ *
+ * @return {JSX.Element} The rendered React component.
+ */
 const Edit = ({ isSelected }) => {
 	const blockProps = useBlockProps();
 	const onlineEventLink = useSelect(

src/blocks/online-event/index.js

@@ -6,11 +6,21 @@ import { registerBlockType } from '@wordpress/blocks';
  * Internal dependencies.
  */
 import edit from './edit';
-
 import metadata from './block.json';
-
 import './style.scss';
 
+/**
+ * Register the GatherPress Online Event block.
+ *
+ * This code registers the GatherPress Online Event block in the WordPress block editor.
+ * It uses the block metadata from the 'block.json' file and associates it with the
+ * edit component for rendering in the editor. The 'save' function is set to null as
+ * the block doesn't have a front-end representation and is only used in the editor.
+ *
+ * @since 1.0.0
+ *
+ * @return {void}
+ */
 registerBlockType(metadata, {
 	edit,
 	save: () => null,

src/blocks/online-event/online-event.js

@@ -9,6 +9,17 @@ import { createRoot } from '@wordpress/element';
  */
 import OnlineEvent from '../../components/OnlineEvent';
 
+/**
+ * Initialize the rendering of GatherPress Online Event blocks.
+ *
+ * This code initializes the rendering of GatherPress Online Event blocks
+ * by selecting all elements with the 'online-event' block name and
+ * rendering the OnlineEvent component inside them with provided attributes.
+ *
+ * @since 1.0.0
+ *
+ * @return {void}
+ */
 domReady(() => {
 	const containers = document.querySelectorAll(
 		`[data-gp_block_name="online-event"]`

src/blocks/rsvp-response/edit.js

@@ -9,6 +9,16 @@ import { useBlockProps } from '@wordpress/block-editor';
 import RsvpResponse from '../../components/RsvpResponse';
 import EditCover from '../../components/EditCover';
 
+/**
+ * Edit component for the GatherPress RSVP Response block.
+ *
+ * This component renders the edit view of the GatherPress RSVP Response block.
+ * It provides an interface for users to view and manage RSVP responses.
+ *
+ * @since 1.0.0
+ *
+ * @return {JSX.Element} The rendered React component.
+ */
 const Edit = () => {
 	const blockProps = useBlockProps();