Document Your JavaScript Code Like a Pro with JSDoc

/**
 * @typedef {Object} Post
 * @property {string} id - Unique identifier of the post.
 * @property {string} title - The title of the post.
 * @property {string} content - Full content of the post.
 * @property {string} author - The author of the post.
 * @property {Date} createdAt - Timestamp of when the post was created.
 * @property {boolean} published - Whether the post is published.
 */

/**
 * @typedef {Object} Comment
 * @property {string} id - Unique identifier of the comment.
 * @property {string} postId - ID of the post this comment belongs to.
 * @property {string} author - Author of the comment.
 * @property {string} text - Content of the comment.
 * @property {Date} createdAt - Timestamp of when the comment was created.
 * @property {boolean} approved - Whether the comment is approved (moderated).
 */

/**
 * @typedef {Object} User
 * @property {string} id - Unique identifier of the user.
 * @property {string} username - Username of the user.
 * @property {string} email - Email address of the user.
 * @property {Date} joinedAt - Date the user registered.
 * @property {boolean} isAdmin - Whether the user has admin privileges.
 */

/**
 * Renders an array of blog posts into an HTML container.
 * @param {Post[]} posts - Array of post objects to render (each having title, content, etc.).
 * @returns {HTMLElement} The container element containing all rendered posts.
 * @example
 * const posts = [
 *   { id: '1', title: 'First Post', content: 'Hello world!', author: 'Alice', createdAt: new Date(), published: true }
 * ];
 * const container = renderPosts(posts);
 * document.body.appendChild(container);
 */
function renderPosts(posts) {
  // ...
}

/**
 * Creates a new blog post.
 * @param {Object} postData - The data for the new post.
 * @param {string} postData.title - The title of the post.
 * @param {string} postData.content - The content of the post.
 * @param {string} postData.author - The author of the post.
 * @returns {Promise<Post>} A promise that resolves to the created post object.
 * @example
 * createPost({ title: 'New Post', content: 'Hello!', author: 'Bob' })
 *   .then(newPost => console.log('Created post ID:', newPost.id));
 */
function createPost(postData) {
  // ...
}

/**
 * Updates an existing blog post by ID.
 * @param {string} postId - ID of the post to update.
 * @param {Object} updates - Fields to update (e.g., title, content).
 * @returns {Promise<Post>} A promise that resolves to the updated post object.
 * @example
 * editPost('1', { title: 'Updated Title' })
 *   .then(updated => console.log('Post now has title:', updated.title));
 */
function editPost(postId, updates) {
  // ...
}

/**
 * Posts a new comment to a blog post.
 * @param {string} postId - ID of the post to comment on.
 * @param {Object} commentData - The data for the new comment.
 * @param {string} commentData.author - Comment author's name or ID.
 * @param {string} commentData.text - The comment text.
 * @returns {Promise<Comment>} A promise resolving to the created comment object.
 * @example
 * addComment('1', { author: 'Charlie', text: 'Great post!' })
 *   .then(comment => console.log('Comment ID:', comment.id));
 */
function addComment(postId, commentData) {
  // ...
}

/**
 * Deletes a comment by its ID.
 * @param {string} commentId - Unique identifier of the comment to delete.
 * @returns {Promise<void>} A promise that resolves when the comment is deleted.
 * @example
 * deleteComment('42').then(() => console.log('Comment deleted'));
 */
function deleteComment(commentId) {
  // ...
}

/**
 * Approves or rejects a pending comment (for moderation).
 * @param {string} commentId - ID of the comment to moderate.
 * @param {boolean} isApproved - `true` to approve, `false` to reject.
 * @returns {Promise<Comment>} A promise resolving to the updated comment object.
 * @example
 * moderateComment('42', true).then(updated => console.log('Comment approved:', updated.approved));
 */
function moderateComment(commentId, isApproved) {
  // ...
}

/**
 * Registers a new user.
 * @param {Object} userData - The new user's data.
 * @param {string} userData.username - Desired username.
 * @param {string} userData.email - User's email address.
 * @param {string} userData.password - Plaintext password for the account.
 * @returns {Promise<User>} A promise that resolves to the created user object.
 * @example
 * registerUser({ username: 'jdoe', email: 'jdoe@example.com', password: 's3cr3t' })
 *   .then(user => console.log('Registered user ID:', user.id));
 */
function registerUser(userData) {
  // ...
}

/**
 * Authenticates a user with a username and password.
 * @param {string} username - The user's username.
 * @param {string} password - The user's password.
 * @returns {Promise<boolean>} A promise that resolves to `true` if credentials are valid.
 * @example
 * loginUser('jdoe', 's3cr3t').then(success => console.log('Login successful:', success));
 */
function loginUser(username, password) {
  // ...
}

/**
 * Logs out the current user (invalidates the session).
 * @returns {void} Does not return a value; ends the user's session.
 * @example
 * logoutUser();
 */
function logoutUser() {
  // ...
}

/**
 * Publishes a blog post (makes it visible to the public).
 * @param {string} postId - ID of the post to publish.
 * @returns {Promise<Post>} A promise resolving to the published post.
 * @example
 * publishPost('1').then(post => console.log('Published:', post.published));
 */
function publishPost(postId) {
  // ...
}

/**
 * Unpublishes a blog post (hides it from the public view).
 * @param {string} postId - ID of the post to unpublish.
 * @returns {Promise<Post>} A promise resolving to the unpublished post.
 * @example
 * unpublishPost('1').then(post => console.log('Published status:', post.published));
 */
function unpublishPost(postId) {
  // ...
}

/**
 * Deletes a blog post by its ID.
 * @param {string} postId - ID of the post to delete.
 * @returns {Promise<void>} A promise resolving when deletion completes.
 * @example
 * deletePost('1').then(() => console.log('Post deleted'));
 */
function deletePost(postId) {
  // ...
}

/**
 * Bans (deactivates) a user by their ID.
 * @param {string} userId - ID of the user to ban.
 * @returns {Promise<User>} A promise resolving to the updated user object.
 * @example
 * banUser('42').then(user => console.log('User banned:', user.isAdmin === false));
 */
function banUser(userId) {
  // ...
}

/**
 * Formats a JavaScript `Date` into a readable string.
 * @param {Date} date - The date to format.
 * @param {string} [locale] - Optional locale string (default is "en-US").
 * @returns {string} The date formatted as a string.
 * @example
 * console.log(formatDate(new Date(), 'en-GB')); // e.g., "25/06/2025"
 */
function formatDate(date, locale = 'en-US') {
  // ...
}

/**
 * Truncates text to a maximum length, adding an ellipsis if needed.
 * @param {string} text - The text to truncate.
 * @param {number} maxLength - Maximum allowed length of the text.
 * @returns {string} The truncated text (with “…” if it was too long).
 * @example
 * console.log(truncateText('Hello World', 5)); // "Hello…"
 */
function truncateText(text, maxLength) {
  // ...
}