From 676ee7d78b1be25fd79eeda4582f15159a26d24d Mon Sep 17 00:00:00 2001 From: phucd5 Date: Mon, 27 Nov 2023 15:23:37 -0500 Subject: [PATCH] updated frontend documentation --- app/newHere1/newHere/ContentView.swift | 23 +++--- app/newHere1/newHere/CustomARView.swift | 22 ++--- .../newHere/CustomARViewRepresentable.swift | 26 +++--- app/newHere1/newHere/Friends.swift | 36 +++++---- app/newHere1/newHere/Home.swift | 41 ++++++---- .../newHere/LocationDataManager.swift | 81 ++++++++++++------- app/newHere1/newHere/LoginView.swift | 34 +++++--- app/newHere1/newHere/Message.swift | 35 ++++---- app/newHere1/newHere/Messages.swift | 29 ++++--- app/newHere1/newHere/Post.swift | 39 ++++----- app/newHere1/newHere/Profile.swift | 55 +++++++++---- app/newHere1/newHere/Registration.swift | 28 ++++--- app/newHere1/newHere/newHereApp.swift | 18 +++-- 13 files changed, 273 insertions(+), 194 deletions(-) diff --git a/app/newHere1/newHere/ContentView.swift b/app/newHere1/newHere/ContentView.swift index 3212175..7feb2fd 100644 --- a/app/newHere1/newHere/ContentView.swift +++ b/app/newHere1/newHere/ContentView.swift @@ -1,15 +1,18 @@ -// -// ContentView.swift -// newHere -// -// Created by Eric Wang on 10/28/23. -// -// Description: -// This file defines the ContentView struct, which serves as the main view for the application. -// It handles user authentication and navigation between the HomePage and Login views. - import SwiftUI +/** + `ContentView`: The root view of the application. + + Manages user authentication state to toggle between `HomePageView` and `LoginView`. + - `isAuthenticated`: State variable to track authentication status. + - `locationDataManager`: Observed object to manage location data. + + View Logic: + - Displays `HomePageView` with `locationDataManager` if user is authenticated. + - Shows `LoginView` to handle user authentication otherwise. + + `ContentView_Previews`: Provides a preview of `ContentView` in Xcode. +*/ struct ContentView: View { @State private var isAuthenticated = false @State private var isRegistered = false diff --git a/app/newHere1/newHere/CustomARView.swift b/app/newHere1/newHere/CustomARView.swift index e162fd5..5b8b663 100644 --- a/app/newHere1/newHere/CustomARView.swift +++ b/app/newHere1/newHere/CustomARView.swift @@ -1,18 +1,18 @@ -// -// CustomARView.swift -// new_here -// -// Created by TRACY LI on 2023/10/28. -// -// Description: -// This file defines a CustomARView class, which is a subclass of ARView from RealityKit. -// It's designed to be used for augmented reality experiences within the 'new_here' application. - import ARKit import RealityKit import SwiftUI -/// CustomARView is a subclass of ARView for creating custom AR experiences. +/** + * CustomARView Class + * + * This class extends ARView to provide custom Augmented Reality (AR) experiences. + * It includes initializers for setting up the view with a specific frame or using the device's main screen bounds. + * + * Methods: + * 1. init(frame: CGRect): Initializes the view with a specified frame. + * 2. init(coder: NSCoder): Required initializer for decoding, not implemented. + * 3. init(): Convenience initializer that sets up the view using the main screen bounds. + */ class CustomARView: ARView { /// Initializes and returns a newly allocated view object with the specified frame rectangle. required init (frame frameRect: CGRect){ diff --git a/app/newHere1/newHere/CustomARViewRepresentable.swift b/app/newHere1/newHere/CustomARViewRepresentable.swift index 046481c..382ae59 100644 --- a/app/newHere1/newHere/CustomARViewRepresentable.swift +++ b/app/newHere1/newHere/CustomARViewRepresentable.swift @@ -1,17 +1,21 @@ -// -// CustomARViewRepresentable.swift -// new_here -// -// Created by TRACY LI on 2023/10/28. -// -// Description: -// This Swift file defines a SwiftUI UIViewRepresentable for integrating ARKit functionality. -// It allows for rendering AR content, such as 3D bubbles with messages, in the 'new_here' application. -// - import SwiftUI import ARKit +/** + * CustomARViewRepresentable + * + * A SwiftUI view representable integrating ARKit's ARSCNView into a SwiftUI view context. + * It facilitates augmented reality features, specifically focusing on rendering messages as 3D objects within an AR environment. + * The struct uses environment objects to manage state related to messages and interacts with ARKit for real-time AR functionalities. + * + * Key Functions: + * - makeUIView(context:): Configures and returns an ARSCNView for AR content rendering. + * - updateUIView(_:context:): Updates the AR view when new messages are available. + * - makeCoordinator(): Creates a coordinator for handling ARSCNViewDelegate methods. + * - plantBubbleNode(to:message:): Plants a bubble node with a message in the AR scene. + * - renderBubbleNodeHistory(to:messages:): Renders a history of messages as bubble nodes in random positions. + * - newBubbleNode(to:message:position:): Creates a new bubble node with a message at a specified position. + */ struct CustomARViewRepresentable: UIViewRepresentable { // Environment objects for message and fetched messages states @EnvironmentObject var messageState: MessageState diff --git a/app/newHere1/newHere/Friends.swift b/app/newHere1/newHere/Friends.swift index 7e5f29f..caaab9e 100644 --- a/app/newHere1/newHere/Friends.swift +++ b/app/newHere1/newHere/Friends.swift @@ -1,22 +1,26 @@ -// Description: SwiftUI View for managing the user's friends. - -//This view presents a pop-up interface for users to search, add, and delete friends. It includes a top bar with a close button, a search bar with an add friend button, and a list displaying the user's friends with delete functionality. -// -//Properties: -//- isPresented: Binding to control the visibility of the pop-up. -//- userId: Binding to represent the current user's ID. -//- friendsList: State variable to hold the list of user's friends. -//- errorMessage: State variable to handle and display errors. -//- searchText: State variable for input in the search bar. -// -//Functionality: -//- Users can search for friends using the search bar. -//- The "Add Friend" button triggers the addition of a friend. -//- Friend entries include a delete button for removing friends. -//- Errors, if any, are displayed at the top of the view. import SwiftUI +/** + * Friends View + * + * A SwiftUI view for managing a user's friends list. It allows users to search, add, and delete friends. + * The view is presented modally and includes a dynamic list of friends with individual delete options. + * It utilizes @Binding to control the presentation state, and @State for managing the friends list, error messages, and search text. + * + * Features: + * - Top bar with a close button to dismiss the view. + * - Search bar for filtering friends or adding new ones. + * - Dynamic list of friends with an option to delete individual friends. + * - Error handling with user feedback. + * + * Lifecycle: + * - The friends list is fetched and updated when the view appears. + * + * External Dependencies: + * - The view expects functions for adding and deleting friends, and for fetching the full friends list. + * - Ensure functions like `getAllUserFriends`, `addFriendByName`, and `deleteFriendByName` are defined with appropriate signatures. + */ struct Friends: View { @Binding var isPresented: Bool diff --git a/app/newHere1/newHere/Home.swift b/app/newHere1/newHere/Home.swift index b2eacf3..b6d6a9c 100644 --- a/app/newHere1/newHere/Home.swift +++ b/app/newHere1/newHere/Home.swift @@ -1,27 +1,36 @@ -// -// Home.swift -// here -// -// Created by Lindsay Chen on 10/14/23. -// -// Description: -// This file defines the HomePageView and associated state management classes for the application. -// It integrates ARKit and manages UI components for messages, posts, and user profile. - import SwiftUI import ARKit -/// Manages the state of the current message in the application. +/** + * MessageState + * + * A class that manages the state of the current message in the application. + * It is an observable object that can be used in SwiftUI views to react to changes in the current message state. + */ class MessageState: ObservableObject { @Published var currentMessage: Message? } -/// Manages the fetched messages state in the application. +/** + * FetchedMessagesState + * + * A class that manages the state of messages fetched from a data source in the application. + * It is an observable object that tracks an array of 'Message' objects. + */ class FetchedMessagesState: ObservableObject { var fetchedMessages: [Message]? } -/// The main view for the home page of the application. +/** + * HomePageView + * + * The main view for the home page of the AR application. This view integrates an AR experience using CustomARViewRepresentable + * and provides a user interface for navigating to different features such as profiles, messages, and posts. + * It manages various UI states using @State and @StateObject properties and provides sheets for displaying popups. + * + * The view overlays control buttons over the AR view and presents modals for profiles, messages, and posts based on user interaction. + * It utilizes @EnvironmentObject to inject and use LocationDataManager within the view hierarchy. + */ struct HomePageView: View { @State private var isShowingProfile = false @State private var isShowingMessages = false @@ -99,7 +108,11 @@ struct HomePageView: View { } } -/// A preview provider for HomePageView, used for rendering the view in Xcode's canvas. +/** + * HomePageView_Previews + * + * A preview provider for HomePageView, facilitating the rendering of the HomePageView in Xcode's canvas. + */ struct HomePageView_Previews: PreviewProvider { static var previews: some View { HomePageView() diff --git a/app/newHere1/newHere/LocationDataManager.swift b/app/newHere1/newHere/LocationDataManager.swift index a35d31e..f9702e3 100644 --- a/app/newHere1/newHere/LocationDataManager.swift +++ b/app/newHere1/newHere/LocationDataManager.swift @@ -1,29 +1,37 @@ -// Description: LocationDataManager Class: Manages location-related data and updates using Core Location. Converts location data to/from GeoJSON format. - -//GeoJSONPoint Struct: Represents a GeoJSON Point with latitude and longitude coordinates. Provides conversion to CLLocation. -// -//CLLocation Extension: Adds a method to convert CLLocation to GeoJSONPoint. - import CoreLocation import Combine +/** + * GeoJSONError + * + * Used to represent specific error conditions + * encountered when working with GeoJSON data, particularly during validation or conversion processes. + * + * Cases: + * - invalidType: Indicates an error due to an invalid or unexpected GeoJSON type. + * - invalidCoordinates: Signifies an error when GeoJSON coordinates are invalid, missing, or malformed. + */ enum GeoJSONError: Error { case invalidType case invalidCoordinates } -// This Codable struct represents a GeoJSON Point with latitude and longitude coordinates. - -//Properties: -//- type: String representing the GeoJSON type (e.g., "Point"). -//- coordinates: Array of Doubles representing latitude and longitude. -// -//Initializer: -//- Initializes a GeoJSONPoint with latitude and longitude, setting the type to "Point". -// -//Functions: -//- toCLLocation(): Converts GeoJSONPoint to CLLocation. - +/** + * GeoJSONPoint + * + * Represents a GeoJSON Point with latitude and longitude coordinates. It provides a method to convert to CLLocation and is + * Codable for easy serialization/deserialization. + * + * Properties: + * - type: A String representing the GeoJSON type, typically "Point". + * - coordinates: An array of Doubles representing latitude and longitude. + * + * Initializer: + * - Initializes a GeoJSONPoint with latitude and longitude, setting the type to "Point". + * + * Functions: + * - toCLLocation(): Converts a GeoJSONPoint to a CLLocation object, validating the type and coordinates format. + */ struct GeoJSONPoint: Codable { let type: String let coordinates: [Double] @@ -46,6 +54,15 @@ struct GeoJSONPoint: Codable { } } +/** + * CLLocation Extension + * + * Adds functionality to the CLLocation class to support conversion to a GeoJSONPoint. This extension enriches CLLocation objects + * with the ability to be easily transformed into a GeoJSON compatible format. + * + * Functions: + * - toGeoJSONPoint(): Converts a CLLocation instance to a GeoJSONPoint, enabling CLLocation objects to be represented in the GeoJSON format. + */ extension CLLocation { // Convert CLLocation to GeoJSONPoint func toGeoJSONPoint() -> GeoJSONPoint { @@ -53,18 +70,22 @@ extension CLLocation { } } -// This class manages location-related data and interactions, including handling Core Location updates and converting location data to/from GeoJSON format. - -//Properties: -//- location: Published property representing the current CLLocation. -//- locationManager: CLLocationManager instance for managing location updates. -// -//Initializer: -//- Initializes a new LocationDataManager object, setting up the CLLocationManager and starting location updates. -// -//Functions: -//- locationManager(_:didUpdateLocations:): Delegate method called when location updates occur, updating the location property. - +/** + * LocationDataManager + * + * Manages location-related data and updates using Core Location. This class is responsible for handling Core Location updates + * and converting location data to/from GeoJSON format. It uses Combine's @Published property to provide observable location updates. + * + * Properties: + * - location: A published property representing the current CLLocation. + * - locationManager: An instance of CLLocationManager for managing location updates. + * + * Initializer: + * - Initializes a new LocationDataManager object, setting up the CLLocationManager and starting location updates. + * + * Functions: + * - locationManager(_:didUpdateLocations:): A delegate method called when location updates occur, updating the location property. + */ class LocationDataManager: NSObject, ObservableObject, CLLocationManagerDelegate { @Published var location: CLLocation? private var locationManager = CLLocationManager() diff --git a/app/newHere1/newHere/LoginView.swift b/app/newHere1/newHere/LoginView.swift index ad3d2fe..a08b9af 100644 --- a/app/newHere1/newHere/LoginView.swift +++ b/app/newHere1/newHere/LoginView.swift @@ -1,14 +1,3 @@ -// -// LoginView.swift -// newHere -// -// Created by TRACY LI on 2023/11/7. -// -// Description: -// This Swift file defines the LoginView, which is responsible for user login in the 'newHere' application. -// It includes input fields for username and password, and login logic to communicate with a remote server. -// - import SwiftUI // Define the URL and API Key for the login API @@ -18,6 +7,29 @@ let logApiKey = "qe5YT6jOgiA422_UcdbmVxxG1Z6G48aHV7fSV4TbAPs" let userId = UserDefaults.standard.string(forKey: "UserId") ?? "" let userName = UserDefaults.standard.string(forKey: "UserName") ?? "" + +/** + * LoginView + * + * Handles user authentication in the application. + * It allows users to input their username and password, and to log in to the application. + * The view also provides a navigation link to the registration view for new users. + * + * Properties: + * - username, password: State variables to hold user input for authentication. + * - isRegistered: State variable indicating the registration status of the user. + * - isAuthenticated: Binding variable to manage authentication status. + * - showingAlert, alertMessage: State variables for handling alert presentations and messages. + * + * Functions: + * - LogInUser(): Handles the login logic, including validation of user input, preparing the request, + * and handling the response from the login API. + * + * Note: + * - Constants like 'loginUrlString' and 'logApiKey' are defined outside the struct for API interaction. + * - UserDefaults is used for storing user information such as 'UserId' and 'UserName'. + */ + struct LoginView: View { // User input fields @State internal var username: String = "" diff --git a/app/newHere1/newHere/Message.swift b/app/newHere1/newHere/Message.swift index 198c90d..2336b23 100644 --- a/app/newHere1/newHere/Message.swift +++ b/app/newHere1/newHere/Message.swift @@ -1,26 +1,21 @@ -// -// Message.swift -// newHere -// -// Created by Eric Wang on 10/28/23. -// - -// Description: This class represents a message object, including its unique identifier, associated user ID, geographic location, and message content. - -//Properties: -//- id: A unique identifier for the message. -//- user_id: The user ID of the sender associated with the message. -//- location: A CLLocation object representing the geographic location associated with the message. -//- messageStr: The string content of the message. -// -//Initializer: -//- Initializes a new Message object with the provided parameters. -// -//Note: This class is utilized for managing messages within the application and may be used in conjunction with location-based features. - import Foundation import CoreLocation + +/** + * Message Class + * + * A class representing a message with identifiers, location, and content. + * + * Properties: + * - id: String for message ID. + * - user_id: String for user ID. + * - location: CLLocation for geographical location. + * - messageStr: String for message content. + * + * Initialization: + * - Initializes with id, user_id, location, and messageStr. + */ class Message { var id: String var user_id: String diff --git a/app/newHere1/newHere/Messages.swift b/app/newHere1/newHere/Messages.swift index 0655090..b59db0d 100644 --- a/app/newHere1/newHere/Messages.swift +++ b/app/newHere1/newHere/Messages.swift @@ -1,17 +1,15 @@ -// -// Messages.swift -// here -// -// Created by Eric Wang on 10/14/23. -// -// Description: -// This file defines the MessagesPopup view, which is used to display a popup of messages -// within the 'here' application. It includes a background image, a list of messages, and -// a close button to dismiss the view. - import SwiftUI -/// View for displaying a popup with messages. +/** + * MessagesPopup + * + * A SwiftUI view for displaying a popup containing message buttons. It uses a binding variable to control its visibility. + * + * Features: + * - Background image for aesthetic enhancement. + * - A close button to dismiss the popup. + * - A list of message buttons created in a loop, each with a profile picture and title. + */ struct MessagesPopup: View { @Binding var isPresented: Bool // Binding to control the visibility of the popup @@ -58,7 +56,12 @@ struct MessagesPopup: View { } } -/// Subview for displaying a profile picture. +/** + * ProfilePicture + * + * A subview within MessagesPopup for displaying a profile picture. + * It presents an image in a circular shape, used alongside message titles in MessagesPopup. + */ struct ProfilePicture: View { var body : some View { Image("profilePicture") diff --git a/app/newHere1/newHere/Post.swift b/app/newHere1/newHere/Post.swift index 05ac14b..d8036ef 100644 --- a/app/newHere1/newHere/Post.swift +++ b/app/newHere1/newHere/Post.swift @@ -1,31 +1,22 @@ -// -// Message_View.swift -// here -// -// Created by Liyang Wang on 10/10/23. -// - -// Description: SwiftUI View for displaying and posting messages. - -//This view includes a pop-up interface for composing and sharing messages. Users can input text, share content, and post messages to the server. The interface is designed with SwiftUI elements, allowing dynamic adjustments based on screen geometry. -// -//Properties: -//- isPresented: Binding to control the visibility of the pop-up. -//- noteMessage: State variable to hold the message text. -//- messageState: EnvironmentObject for managing message-related state. -//- senderName: Constant string representing the username. -//- locationDataManager: EnvironmentObject for handling location data. -// -//Functionality: -//- Users can compose messages using a TextEditor. -//- Share and post buttons trigger respective actions. -//- Messages are posted to the server with associated user and location data. - import SwiftUI import CoreLocation import Foundation - +/** + * PostsPopup + * + * A SwiftUI view component for creating and posting messages. It offers an interactive interface for users to write and share posts. + * The view uses a binding variable to control its visibility and environment objects for state and location data management. + * + * Features: + * - TextEditor for message input. + * - Share and Post buttons for user interaction. + * - GeometryReader and ZStack for dynamic, layered UI layout. + * - Integration with location data and message state for post creation. + * + * Note: + * - It includes a close button to dismiss the view and leverages environment objects like `messageState` and `locationDataManager`. + */ struct PostsPopup: View { @Binding var isPresented: Bool // @Binding var storedMessages: [Message] diff --git a/app/newHere1/newHere/Profile.swift b/app/newHere1/newHere/Profile.swift index 7a9c077..9a1b70f 100644 --- a/app/newHere1/newHere/Profile.swift +++ b/app/newHere1/newHere/Profile.swift @@ -1,16 +1,19 @@ -// -// Profile.swift -// here -// -// Created by Lindsay Chen on 10/13/23. -// -// Description: -// This file defines the ProfilePopup view along with its subviews such as ProfileHeader, ProfileButtons, -// ProfileStats, and PostGrid for the 'here' application. It includes functionality for displaying user profiles -// with options to view and edit profile details. - import SwiftUI +/** + * ProfilePopup + * + * A SwiftUI view for displaying a user's profile in a popup format. It includes a header, profile statistics, and options to interact with the profile, such as viewing friends and posts. + * + * Properties: + * - isPresented: Binding to control the visibility of the popup. + * - isShowingFriends: State to manage the display of friends list. + * + * Subviews: + * - ProfileHeader: Displays the user's profile picture and basic information. + * - ProfileStats: Shows key statistics like the number of notes and friends. + * - PostGrid: A placeholder for displaying the user's posts in a grid layout. + */ struct ProfilePopup: View { @Binding var isPresented: Bool // Added binding to control visibility @State private var isShowingFriends: Bool = false @@ -58,7 +61,11 @@ struct ProfilePopup: View { } } -/// View for displaying the user's profile header. +/** + * ProfileHeader + * + * A subview within ProfilePopup that displays the user's profile picture, name, and a short bio. + */ struct ProfileHeader: View { var body: some View { HStack { @@ -87,7 +94,11 @@ struct ProfileHeader: View { } } -/// View for displaying profile action buttons. +/** + * ProfileButtons + * + * A subview within ProfilePopup that provides action buttons for editing the user's profile and adding friends. + */ struct ProfileButtons: View { var body: some View { HStack { @@ -117,7 +128,11 @@ struct ProfileButtons: View { } } -/// View for displaying profile statistics. +/** + * ProfileStats + * + * A subview within ProfilePopup for displaying key statistics about the user's profile, such as the number of notes and friends. + */ struct ProfileStats: View { let stats: [(title: String, value: String)] = [ ("Notes", "10"), @@ -145,7 +160,11 @@ struct ProfileStats: View { } } -/// View for displaying individual profile stat item. +/** + * ProfileStatItem + * + * A component within ProfileStats that represents a single statistic item, displaying a title and a value. + */ struct ProfileStatItem: View { let title: String let value: String @@ -163,7 +182,11 @@ struct ProfileStatItem: View { } } -/// View for displaying the posts grid. +/** + * PostGrid + * + * A subview within ProfilePopup intended to display the user's posts in a grid format. Currently serves as a placeholder. + */ struct PostGrid: View { var body: some View { // Placeholder for posts grid diff --git a/app/newHere1/newHere/Registration.swift b/app/newHere1/newHere/Registration.swift index 5a11bf4..07c835d 100644 --- a/app/newHere1/newHere/Registration.swift +++ b/app/newHere1/newHere/Registration.swift @@ -1,20 +1,26 @@ -// -// Registration.swift -// newHere -// -// Created by TRACY LI on 2023/11/4. -// -// Description: -// This file defines the RegistrationView, which is used for user registration in the 'newHere' application. -// It includes form inputs for user details and a registration logic to communicate with a remote server. - import SwiftUI // URL and API Key for registration API let registerUrlString = "https://here-swe.vercel.app/auth/register" let regApiKey = "qe5YT6jOgiA422_UcdbmVxxG1Z6G48aHV7fSV4TbAPs" -/// View for user registration. +/** + * RegistrationView + * + * A SwiftUI view for user registration. It provides text fields for entering personal details and credentials, + * and includes a submission button to register the user. This view also handles the registration logic, + * including data validation and network requests to the registration API. + * + * Properties: + * - firstName, lastName, userName, email, password, confirmPassword: State variables for user input. + * - isRegistered: Binding to track the registration status. + * - isAuthenticated: State to manage authentication status. + * - showingAlert, alertMessage: State variables for alert presentation and messages. + * + * Functions: + * - registerUser(): Handles the registration process, including validating input, creating a request body, + * and making a network request to the registration API. + */ struct RegistrationView: View { @State private var firstName: String = "" @State private var lastName: String = "" diff --git a/app/newHere1/newHere/newHereApp.swift b/app/newHere1/newHere/newHereApp.swift index 3799e70..6f8d366 100644 --- a/app/newHere1/newHere/newHereApp.swift +++ b/app/newHere1/newHere/newHereApp.swift @@ -1,10 +1,14 @@ -// -// newHereApp.swift -// newHere -// -// Created by Eric Wang on 10/28/23. -// - +/** + * newHereApp + * + * The main struct for the 'newHere' SwiftUI application, marked with @main to indicate the entry point of the app. + * It defines the body of the app with a scene configuration. + * + * Scene Configuration: + * - WindowGroup: A container that defines the content of the app's primary window. + * It initializes ContentView as the root view of the application. + */ + import SwiftUI @main