Рекомендации по разработке на Java — 9.2. Javadoc для публичного API

/**
 * Представляет пользователя системы.
 * <p>
 * Объект пользователя содержит информацию о регистрации,
 * правах доступа и предпочтениях. Пользователи создаются
 * через {@link UserService#register} и загружаются через
 * {@link UserRepository#findById}.
 */
public class User {
    
    /**
     * Уникальный идентификатор пользователя в системе.
     * Генерируется автоматически при создании записи в базе данных.
     */
    private final Long id;
    
    /**
     * Адрес электронной почты пользователя.
     * Используется для аутентификации и отправки уведомлений.
     * Должен быть уникальным в пределах системы.
     */
    private final String email;
    
    /**
     * Проверяет, активен ли пользователь.
     * <p>
     * Неактивные пользователи не могут входить в систему,
     * но их данные сохраняются для аудита и восстановления.
     *
     * @return true, если пользователь активен, false в противном случае
     */
    public boolean isActive() {
        return active;
    }
}