Write good help for custom commands in self developed package

Questions
1

I am currently using Wolfram language to develop a package in the field of crystallography, which includes many custom commands, and I’m confused about how to write good help text for these commands. For example, I wrote the following command parameter help text for one of the commands:

AffCrystGroupOnLeft::usage = " AffineCrystGroupOnLeft[ gen1, gen2,
…, method ] AffineCrystGroupOnLeft[ { gen1, gen2, … }, method ]

This command returns a matrix group generated by or ,
which must be affine matrices acting on the left. The group elements
are given in the modulo 1 format to keep all the products within the
unit cell.

The parameter has the following modulo method options: 0 is
the normal method of Mod[{x,y,z}, 1] for the translation vector
{x,y,z}. 1 keep all original components of the translation vector {x,
y, Z} equal to 1 in their original form, i.e., without applying
modulo on them.

The default value of this parameter is 0.";

But I still feel that my description and writing format is rather confusing and poor. Although I have no problem understanding it myself. But how can the above description and format be improved to make it easier for potential users to grasp and clearly understand the meaning?

Regards,
Zhao

2

Formatting:

Zhaousage.png
Zhaousage.png830×299 8.56 KB

Zhao usage.wl (743 Bytes)

3

Hi Hans,

This method needs to write very long single line text and need to be very careful about the use of new line symbol \n, so it is not easy to write, and error-prone.

4

You can also write the text with “normal” linebreaks, as in the attached file.

Zhao usage 2.wl (735 Bytes)

5

Thank you again. I have taken your suggestion and re-formatted the relevant help text.