docs for operations on diffraction objects

[yucongalicechen]

docs for functions in #187, once that issue is finished

[yucongalicechen]

@sbillinge looks like there're already some examples for the operations in the current docs - do we need to add more?

Also, do we want to test metadata of the resulting diffraction objects to ensure it includes all metadata from self and other objects)? I'm asking this because in labpdfproc we have corrected_pattern = diffraction_pattern * absorption_correction and we dump the corrected_pattern in the file which involves metadata.

[sbillinge]

We don't have to check metadata unless we modify the metadata somehow. Right now, it will just inherit the metadata from the LHS DO (I think, right)? We might want to think how we want to handle that in the future and make an issue for a future release.

One idea I had was, if each DO has a uuid (which they do now) we could store the provenance of the new DO, for example, that it was lhs_do.uuid + rhs_do.uuid, for example. In principle we could unroll everything all the way back to recover all metadata this way. But this can get pretty complicated pretty quickly. Let's just leave it as it is for now.

In terms of if we need more examples, just make sure that all the tests are described in the docs in words.

We may want to put in the docs that the new DO inherits metadata from the LHS DO or whatever it is.

[yucongalicechen]

Yeah, it inherits the metadata from the LHS. I put this in a new issue #296. Will work on the docs

[bobleesj]

Yeah, it inherits the metadata from the LHS. I put this in a new issue #296. Will work on the docs

I have to hangout with my family and will be back later this evening. Just wanted to share I have added a through doc string on __add__ and for other operations, it's pretty much the same. Examples can be easily found from the tests in the second code snippet below:

    def __add__(self, other):
        """Add a scalar value or another DiffractionObject to the yarray of the
        DiffractionObject.

        Parameters
        ----------
        other : DiffractionObject or int or float
            The object to add to the current DiffractionObject. If `other` is a scalar value,
            it will be added to all yarray. The length of the yarray must match if `other` is
            an instance of DiffractionObject.

        Returns
        -------
        DiffractionObject
            The new and deep-copied DiffractionObject instance after adding values to the yarray.

        Raises
        ------
        ValueError
            Raised when the length of the yarray of the two DiffractionObject instances do not match.
        TypeError
            Raised when the type of `other` is not an instance of DiffractionObject, int, or float.

        Examples
        --------
        Add a scalar value to the yarray of the DiffractionObject instance:
        >>> new_do = my_do + 10.1
        >>> new_do = 10.1 + my_do

        Add the yarray of two DiffractionObject instances:
        >>> new_do = my_do_1 + my_do_2
        """

and

    if operation == "add":
        do_1_y_modified = do_1 + do_2
        do_2_y_modified = do_2 + do_1
    elif operation == "sub":
        do_1_y_modified = do_1 - do_2
        do_2_y_modified = do_2 - do_1
    elif operation == "mul":
        do_1_y_modified = do_1 * do_2
        do_2_y_modified = do_2 * do_1
    elif operation == "div":
        do_1_y_modified = do_1 / do_2
        do_2_y_modified = do_2 / do_1

[bobleesj]

I will be also doing an overall fix on docstrings so if you see any poorly written ones, I will most likely fix them.