condense doc for sqrt into single docstring

[varuntrehan7]

I was able to clear up the docs from various .md files ( if this was not what was asked please let me know I will undo it) and I am assuming the next step is that there needs to be a generic docstring wrapper for sqrt that goes somewhere which I am not sure where, please let me know. Thanks!

[lgoettgens]

You now removed mentions of the docstrings from the manual (the md pages), but you additionally need to remove the docstrings themselves.

I am assuming the next step is that there needs to be a generic docstring wrapper for sqrt that goes somewhere which I am not sure where, please let me know.

Please have a look at #2186. I would suggest to put your generic docstring right below the generic one added there for is_square.

[varuntrehan7]

You now removed mentions of the docstrings from the manual (the md pages), but you additionally need to remove the docstrings themselves.

I am assuming the next step is that there needs to be a generic docstring wrapper for sqrt that goes somewhere which I am not sure where, please let me know.

Please have a look at #2186. I would suggest to put your generic docstring right below the generic one added there for is_square.

Got it, thanks!

[fingolfin]

That's already looking quite good, thanks!

One thing that is missing is adding both is_square and Base.sqrt(::NCRingElem) in a central place to the manual.

My suggestion for the moment would be to add a section ## Square root to the file docs/src/ring.md -- I would add it before the ## Miscellaneous section.

In there, you would write something like this (untested):

## Square root

Some rings allow computing square roots.

```@docs
is_square
sqrt(::NCRingElem)
```

I am sure this can be improved, but we need to start somewhere.

[varuntrehan7]

That's already looking quite good, thanks!

One thing that is missing is adding both is_square and Base.sqrt(::NCRingElem) in a central place to the manual.

My suggestion for the moment would be to add a section ## Square root to the file docs/src/ring.md -- I would add it before the ## Miscellaneous section.

In there, you would write something like this (untested):

## Square root

Some rings allow computing square roots.

```@docs
is_square
sqrt(::NCRingElem)

I am sure this can be improved, but we need to start somewhere.

That's already looking quite good, thanks!

One thing that is missing is adding both is_square and Base.sqrt(::NCRingElem) in a central place to the manual.

My suggestion for the moment would be to add a section ## Square root to the file docs/src/ring.md -- I would add it before the ## Miscellaneous section.

In there, you would write something like this (untested):

## Square root

Some rings allow computing square roots.

```@docs
is_square
sqrt(::NCRingElem)

I am sure this can be improved, but we need to start somewhere.

thanks for the suggestion, I tried to improve it a bit please let me know if the implementation matches the pattern you'd like it here.

[fingolfin]

@varuntrehan7 this is marked as a draft -- do you have anything you still plan to do with this then? Otherwise, please just use the "Ready for review" button.

[fingolfin]

The docstrings follow below, and IMHO there is no point for this redundancy.

Suggested change

	while others only implement `is_square`. If `check=false`, the square root
	check may be omitted.
	The following entries link to the generic interface documentation:
	while others only implement `is_square`.

[fingolfin]

• I am not sure about "Many" -- how do you count this
• it's not just about rings in AbstractAlgebra
• the list of functions is redundant with the docstrings that follow right below.

Suggested change

	Many rings in AbstractAlgebra provide functionality for detecting and computing
	square roots. Two functions form the basic interface:
	- `is_square(a)` – return `true` if the element `a` is a square in its ring.
	- `sqrt(a; check=true)` – return a square root of `a`, when available.
	Rings may implement functionality for detecting and computing square roots.

[varuntrehan7]

okay got it.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.00%. Comparing base (1a7d93c) to head (d4eecc6).
⚠️ Report is 6 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2226   +/-   ##
=======================================
  Coverage   88.00%   88.00%           
=======================================
  Files         127      127           
  Lines       31803    31803           
=======================================
  Hits        27989    27989           
  Misses       3814     3814           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.