📝 112 documentation general documentation (#116)

* 📝 documentation updated for pinia stores * 📝 documentation updated for types * 📝 documentation updated for views * 📝 documentation updated for util * 🚚 moved to utils * 📝 documentation updated for composables * 🚚 renamed to match other api composables * 📝 documentation updated for api composables * 📝 documentation updated for components * 📝 documentation updated for filter components * ✨ introduced debouncer for search :D * 📝 documentation updated for common components * 📝 documentation updated for ad components * 🐛 small bug * 📝 Updated documentation for ad edit components * 📝 Updated documentation for ad details components --------- Co-authored-by: jannik.lange <[email protected]>
it-at-m · Jan 24, 2025 · cb0d5b8 · cb0d5b8
1 parent 39b7f3a
commit cb0d5b8
Show file tree

Hide file tree

Showing 40 changed files with 374 additions and 208 deletions.
diff --git a/anzeigen-frontend/index.html b/anzeigen-frontend/index.html
@@ -15,6 +15,7 @@
 
   <body>
     <div id="app"></div>
+    <!-- Designed with ❤️ by [langehm](https://github.com/langehm/) -->
     <script
       type="module"
       src="/src/main.ts"

diff --git a/anzeigen-frontend/src/components/Ad/AdArtChip.vue b/anzeigen-frontend/src/components/Ad/AdArtChip.vue
@@ -14,7 +14,14 @@ const { isOffer = false } = defineProps<{
   isOffer?: boolean;
 }>();
 
+/**
+ * Computes the text based on the offer status.
+ */
 const computedText = computed(() => (isOffer ? "Biete" : "Suche"));
+
+/**
+ * Computes the icon based on the offer status.
+ */
 const computedIcon = computed(() =>
   isOffer ? "mdi-hand-extended-outline" : "mdi-binoculars"
 );

diff --git a/anzeigen-frontend/src/components/Ad/AdCard.vue b/anzeigen-frontend/src/components/Ad/AdCard.vue
@@ -109,7 +109,7 @@ import AdEditButton from "@/components/Ad/AdEditButton.vue";
 import AdPrice from "@/components/Ad/AdPrice.vue";
 import AdViewCountChip from "@/components/Ad/AdViewCountChip.vue";
 import { useDialogEventBus } from "@/composables/useEventBus";
-import { PREVIEW_IMAGE_FILE_URI_PREFIX } from "@/Constants";
+import { PREVIEW_IMAGE_FILE_URI_PREFIX, ROUTES_AD } from "@/Constants";
 import { useUserStore } from "@/stores/user";
 
 const router = useRouter();
@@ -122,20 +122,28 @@ const { adTo } = defineProps<{
   adTo: DeepReadonly<AdTO>;
 }>();
 
+/**
+ * Computes whether the ad is an offer based on its ad type.
+ */
 const isOffer = computed(() => adTo.adType === "OFFER");
 
-const belongsToCurrentUser = computed(() => {
-  return adTo.swbUser?.id === userStore.userID;
-});
+/**
+ * Computes whether the ad belongs to the current user based on the user ID.
+ */
+const belongsToCurrentUser = computed(
+  () => adTo.swbUser?.id === userStore.userID
+);
 
 /**
- * Route to a specific ad
- * @param id of the ad
+ * Routes the ad details page with the current clicked ad.
  */
 const routeTo = () => {
-  router.push({ path: "/ad", query: { id: adTo.id } });
+  router.push({ name: ROUTES_AD, query: { id: adTo.id } });
 };
 
+/**
+ * Emits an event to edit the ad when clicked.
+ */
 const clickedEdit = () => {
   dialogBus.emit(AdTOFromJSONTyped(AdTOToJSONTyped(adTo as AdTO), false));
 };
@@ -145,7 +153,7 @@ const clickedEdit = () => {
 .two-line-clamp {
   display: -webkit-box;
   -webkit-box-orient: vertical;
-  -webkit-line-clamp: 2; /* Anzahl der Zeilen, die angezeigt werden sollen */
+  -webkit-line-clamp: 2; /* Number of lines to be displayed */
   overflow: hidden;
 }
 </style>
diff --git a/anzeigen-frontend/src/components/Ad/AdCardContact.vue b/anzeigen-frontend/src/components/Ad/AdCardContact.vue
diff --git a/anzeigen-frontend/src/components/Ad/AdCardText.vue b/anzeigen-frontend/src/components/Ad/AdCardText.vue
diff --git a/anzeigen-frontend/src/components/Ad/AdEditButton.vue b/anzeigen-frontend/src/components/Ad/AdEditButton.vue
@@ -18,12 +18,21 @@ const { isEdit = false } = defineProps<{
   isEdit?: boolean;
 }>();
 
+/**
+ * Computes the text based on whether the component is in edit mode or not.
+ */
 const computedText = computed(() =>
   isEdit ? "Bearbeiten" : "Anzeige erstellen"
 );
 
+/**
+ * Computes the icon based on whether the component is in edit mode or not.
+ */
 const computedIcon = computed(() => (isEdit ? "mdi-pencil" : "mdi-plus"));
 
+/**
+ * Emits a "click" event when the action is triggered.
+ */
 const click = () => emit("click");
 </script>
 

diff --git a/anzeigen-frontend/src/components/Ad/AdPrice.vue b/anzeigen-frontend/src/components/Ad/AdPrice.vue
@@ -22,8 +22,14 @@ const { price } = defineProps<{
   price: number;
 }>();
 
+/**
+ * Computes whether the item is being given away for free based on its price.
+ */
 const toGiveAway = computed(() => price === 0);
 
+/**
+ * Computes the appendix tag based on the price, using a negotiate tag for negative prices.
+ */
 const appendixTag = computed(() => (price < 0 ? NEGOTIATE_TAG : ""));
 </script>
 

diff --git a/anzeigen-frontend/src/components/Ad/AdViewCountChip.vue b/anzeigen-frontend/src/components/Ad/AdViewCountChip.vue
@@ -14,6 +14,10 @@ const { views = 0 } = defineProps<{
   views: number;
 }>();
 
+/**
+ * Computes the icon based on the number of views.
+ * If views are 0 or less, it shows a "closed eye" icon, otherwise it shows a regular "eye" icon.
+ */
 const computedIcon = computed(() =>
   views <= 0 ? "mdi-eye-off-outline" : "mdi-eye-outline"
 );

diff --git a/anzeigen-frontend/src/components/Ad/Details/AdOverview.vue b/anzeigen-frontend/src/components/Ad/Details/AdOverview.vue
@@ -169,10 +169,17 @@ const currentLink = computed(() => window.location.href);
 
 const { call: getFile, data: fileData, loading: getFileLoading } = useGetFile();
 
+/**
+ * Computes the ad type, returning "Suche" for SEEK and "Biete" for other ad types.
+ */
 const adType = computed(() =>
   adDetails.adType === "SEEK" ? "Suche" : "Biete"
 );
 
+/**
+ * Navigates to the user page with the specified user ID.
+ * @param id - The ID of the user.
+ */
 const routeToUser = (id: number) => {
   router.push({
     path: "/board",
@@ -182,6 +189,11 @@ const routeToUser = (id: number) => {
   });
 };
 
+/**
+ * Downloads a file based on the provided ID.
+ * Retrieves the file, creates a Blob, and triggers a download.
+ * @param id - The ID of the file to download.
+ */
 const downloadFile = async (id: number) => {
   await getFile({ id: id });
 

diff --git a/anzeigen-frontend/src/components/Ad/Edit/AdCategorySelector.vue b/anzeigen-frontend/src/components/Ad/Edit/AdCategorySelector.vue
@@ -30,6 +30,11 @@ const emit = defineEmits<{
   "update:modelValue": [modelValue: AdCategory];
 }>();
 
+/**
+ * Emits an update for the selected category when the selection changes.
+ *
+ * @param selection - The selected category (id is extracted for compatibility).
+ */
 const updatedSelection = (selection: AdCategory) => {
   // Type error of v-select. It does not return the category, instead it returns the id.
   const id = selection as number;

diff --git a/anzeigen-frontend/src/components/Ad/Edit/AdDateSelector.vue b/anzeigen-frontend/src/components/Ad/Edit/AdDateSelector.vue
@@ -25,7 +25,10 @@ const emit = defineEmits<{
   "update:modelValue": [modelValue: Date];
 }>();
 
-// TODO replace this with api call
+// TODO replace this with api call - set maximum date!
+/**
+ * computed the displayed date, ever the already selected or a predefined maximum value
+ */
 const computedDate = computed(() => {
   return !modelValue
     ? new Date().setMonth(new Date().getMonth() + 2)

diff --git a/anzeigen-frontend/src/components/Ad/Edit/AdDialog.vue b/anzeigen-frontend/src/components/Ad/Edit/AdDialog.vue
@@ -129,19 +129,30 @@ defineProps<{
 
 const deleteDialog = ref<boolean>(false);
 
+/**
+ * Listens for ad-related events and opens the dialog with the ad data. This a created ad or an empty ad.
+ */
 dialogBus.on((event: AdTO) => {
   isAdCreate.value = !event.id;
   dialog.value = true;
   adTo.value = event;
 });
 
+/**
+ * Handles the confirmation of ad deletion.
+ * Emits the "deactivateAd" event with the ad ID and closes the delete dialog.
+ */
 const confirmedDeletion = async () => {
   if (adTo.value?.id) {
     emit("deactivateAd", adTo.value?.id);
   }
   deleteDialog.value = false;
 };
 
+/**
+ * Handles the creation or updating of an ad.
+ * Emits the appropriate event based on whether it's a new ad or an existing one.
+ */
 const writeAd = async () => {
   if (adTo.value) {
     // eslint-disable-next-line @typescript-eslint/no-unused-expressions
@@ -151,6 +162,9 @@ const writeAd = async () => {
   }
 };
 
+/**
+ * Closes the ad dialog.
+ */
 const close = () => {
   dialog.value = false;
 };

diff --git a/anzeigen-frontend/src/components/Ad/Edit/AdEditStepper.vue b/anzeigen-frontend/src/components/Ad/Edit/AdEditStepper.vue