feat(gui): descriptions of annotations (#803)

* feat(gui): link to user guide

* feat(gui): short help texts in annotation forms

* style: apply automatic fixes of linters

* chore: shorten help text

Co-authored-by: lars-reimann <[email protected]>

Author: lars-reimann

api-editor/gui/src/features/annotations/AnnotationView.tsx

@@ -65,7 +65,7 @@ import {
     showTodoAnnotationForm,
 } from '../ui/uiSlice';
 import { truncate } from '../../common/util/stringOperations';
-import { wrongAnnotationURL } from '../reporting/issueURLBuilder';
+import { wrongAnnotationURL } from '../externalLinks/urlBuilder';
 
 interface AnnotationViewProps {
     target: string;

api-editor/gui/src/features/annotations/MissingAnnotationButton.tsx

@@ -1,7 +1,7 @@
 import { IconButton } from '@chakra-ui/react';
 import React from 'react';
 import { FaFlag } from 'react-icons/fa';
-import { missingAnnotationURL } from '../reporting/issueURLBuilder';
+import { missingAnnotationURL } from '../externalLinks/urlBuilder';
 
 interface MissingAnnotationButtonProps {
     target: string;

api-editor/gui/src/features/annotations/batchforms/AnnotationBatchForm.tsx

@@ -1,24 +1,30 @@
-import { Button, Heading, HStack, Stack } from '@chakra-ui/react';
+import { Button, Heading, HStack, Stack, Text as ChakraText } from '@chakra-ui/react';
 import React from 'react';
 
 interface AnnotationFormProps {
     heading: string;
+    description: string;
     onConfirm: React.MouseEventHandler<HTMLButtonElement>;
     onCancel: React.MouseEventHandler<HTMLButtonElement>;
     children: React.ReactNode;
 }
 
 export const AnnotationBatchForm: React.FC<AnnotationFormProps> = function ({
     heading,
+    description,
     onCancel,
     onConfirm,
     children,
 }) {
     return (
         <Stack spacing={8} p={4}>
-            <Heading as="h3" size="lg">
-                {heading}
-            </Heading>
+            <Stack spacing={4}>
+                <Heading as="h3" size="lg">
+                    {heading}
+                </Heading>
+
+                <ChakraText fontStyle="italic">{description}</ChakraText>
+            </Stack>
 
             <Stack spacing={4}>{children}</Stack>
 

api-editor/gui/src/features/annotations/batchforms/ConstantBatchForm.tsx

@@ -37,6 +37,7 @@ export const ConstantBatchForm: React.FC<ConstantBatchFormProps> = function ({ t
         <TypeValueBatchForm
             targets={filteredTargets}
             annotationType="constant"
+            description="Delete matched parameters and replace references to them with a constant value."
             onUpsertAnnotation={handleUpsertAnnotation}
         />
     );

api-editor/gui/src/features/annotations/batchforms/DestinationBatchForm.tsx

@@ -10,6 +10,7 @@ import { ConfirmAnnotations } from './ConfirmAnnotations';
 interface DestinationBatchFormProps {
     targets: PythonDeclaration[];
     annotationType: string;
+    description: string;
     onUpsertAnnotation: (data: DestinationBatchFormState) => void;
 }
 
@@ -20,6 +21,7 @@ export interface DestinationBatchFormState {
 export const DestinationBatchForm: React.FC<DestinationBatchFormProps> = function ({
     targets,
     annotationType,
+    description,
     onUpsertAnnotation,
 }) {
     const dispatch = useAppDispatch();
@@ -60,6 +62,7 @@ export const DestinationBatchForm: React.FC<DestinationBatchFormProps> = functio
         <>
             <AnnotationBatchForm
                 heading={`Add @${annotationType} Annotations`}
+                description={description}
                 onConfirm={handleSubmit(handleConfirm)}
                 onCancel={handleCancel}
             >

api-editor/gui/src/features/annotations/batchforms/EmptyBatchForm.tsx

@@ -9,13 +9,15 @@ import { ConfirmAnnotations } from './ConfirmAnnotations';
 interface EmptyBatchFormProps {
     targets: PythonDeclaration[];
     annotationType: string;
+    description: string;
     onUpsertAnnotation: () => void;
     targetLabel: string;
 }
 
 export const EmptyBatchForm: React.FC<EmptyBatchFormProps> = function ({
     targets,
     annotationType,
+    description,
     onUpsertAnnotation,
     targetLabel,
 }) {
@@ -45,6 +47,7 @@ export const EmptyBatchForm: React.FC<EmptyBatchFormProps> = function ({
         <>
             <AnnotationBatchForm
                 heading={`Add @${annotationType} Annotations`}
+                description={description}
                 onConfirm={handleConfirm}
                 onCancel={handleCancel}
             >

api-editor/gui/src/features/annotations/batchforms/MoveBatchForm.tsx

@@ -38,6 +38,7 @@ export const MoveBatchForm: React.FC<MoveBatchFormProps> = function ({ targets }
         <DestinationBatchForm
             targets={filteredTargets}
             annotationType="move"
+            description="Move matched global declarations to another module."
             onUpsertAnnotation={handleUpsertAnnotation}
         />
     );

api-editor/gui/src/features/annotations/batchforms/OldNewBatchForm.tsx

@@ -10,6 +10,7 @@ import { ConfirmAnnotations } from './ConfirmAnnotations';
 interface OldNewBatchFormProps {
     targets: PythonDeclaration[];
     annotationType: string;
+    description: string;
     onUpsertAnnotation: (data: OldNewBatchFormState) => void;
 }
 
@@ -21,6 +22,7 @@ export interface OldNewBatchFormState {
 export const OldNewBatchForm: React.FC<OldNewBatchFormProps> = function ({
     targets,
     annotationType,
+    description,
     onUpsertAnnotation,
 }) {
     const dispatch = useAppDispatch();
@@ -65,6 +67,7 @@ export const OldNewBatchForm: React.FC<OldNewBatchFormProps> = function ({
         <>
             <AnnotationBatchForm
                 heading={`Add @${annotationType} Annotations`}
+                description={description}
                 onConfirm={handleSubmit(handleConfirm)}
                 onCancel={handleCancel}
             >

api-editor/gui/src/features/annotations/batchforms/OptionalBatchForm.tsx

@@ -37,6 +37,7 @@ export const OptionalBatchForm: React.FC<OptionalBatchFormProps> = function ({ t
         <TypeValueBatchForm
             targets={filteredTargets}
             annotationType="optional"
+            description="Make matched parameters optional and set their default value."
             onUpsertAnnotation={handleUpsertAnnotation}
         />
     );

api-editor/gui/src/features/annotations/batchforms/RemoveBatchForm.tsx

@@ -35,6 +35,7 @@ export const RemoveBatchForm: React.FC<RemoveBatchFormProps> = function ({ targe
         <EmptyBatchForm
             targets={filteredTargets}
             annotationType="remove"
+            description="Remove matched classes and functions."
             onUpsertAnnotation={handleUpsertAnnotation}
             targetLabel="This will annotate classes and functions."
         />