Repository: sympy/sympy
Pull request: Updated Symbol Docstring
#### References to other Issues or PRs
Fixes #22981 


#### Brief description of what is fixed or changed

Added Explanation, assumptions, Examples, Parameters to the documentation. Added examples about creating symbols by passing Greek symbols and rules for adding subscripts.

#### Other comments

I am new to Open source. Please tell me if changes are required.

#### Release Notes

<!-- Write the release notes for this release below between the BEGIN and END
statements. The basic format is a bulleted list with the name of the subpackage
and the release note for this PR. For example:

* solvers
  * Added a new solver for logarithmic equations.

* functions
  * Fixed a bug with log of integers. Formerly, `log(-x)` incorrectly gave `-log(x)`.

* physics.units
  * Corrected a semantical error in the conversion between volt and statvolt which
    reported the volt as being larger than the statvolt.

or if no release note(s) should be included use:

NO ENTRY

See https://github.com/sympy/sympy/wiki/Writing-Release-Notes for more
information on how to write release notes. The bot will check your release
notes automatically to see if they are formatted correctly. -->

<!-- BEGIN RELEASE NOTES -->
NO ENTRY
<!-- END RELEASE NOTES -->


Problem statement:
Docstring for Symbol is very thin
I linked to the docstring of `Symbol`, which is one of the most widely used objects in SymPy and was surprised at how little information was present in the docstring. This is all it is:

```
class Symbol(AtomicExpr, Boolean):
    """
    Assumptions:
       commutative = True
    You can override the default assumptions in the constructor.
    Examples
    ========
    >>> from sympy import symbols
    >>> A,B = symbols('A,B', commutative = False)
    >>> bool(A*B != B*A)
    True
    >>> bool(A*B*2 == 2*A*B) == True # multiplication by scalars is commutative
    True
    """
```

I would expect this to explain quite a bit more: all assumptions, passing in greek letters, or subscripts, and probably more.

Hints from issue discussion:
@moorepants  I want to work on this issue.
@moorepants I think even the examples used here should not really be used here instead in the documentation we do have symbols and therefore it should be used there.
As a beginner I don't know for sure and it was not mentioned in the documentation but I just think,
`sympy.Symbol` is used to define just a single symbol and for multiple symbols we use `sympy.symbols`
Therefore, while changing the docstring I mentioned this commutative property in `symbols` instead of `Symbol`
and removed Assumptions from `Symbol` do you think it's okay?
> do you think it's okay?

No, I don't.

I think the docstrings for any public module/function/class/method/variable should be complete and helpful. The docstring for `Symbol` is very thin and does not explain everything it can do.
@moorepants I tried updating the docstrings can you please check once?
I don't really know for sure what I should be adding more like what more assumptions are there or are the changes made okay or is there something you expect more to be added I will commit more changes then. 
Hi is this issue still open? If yes I would like to contribute to it.
When the issues are closed, the large green Open near the title will be a large purple Closed. And you don't need to ask to contribute. If there is no PR showing as linked to the issue, it should be safe to open one.
Another thing the docstring should probably contain is a note that Symbols compare equal based on name and assumptions, so `Symbol('x') != Symbol('x', real=True)` even though they both print the same.
All symbols that look the same can be shown in unambiguous form with `disambiguate`:

![image](https://user-images.githubusercontent.com/90703/198849796-53062295-fc31-43aa-ba00-bc0007cc26ca.png)

Anyone wanting to work on this please look at the docstring style guide:
https://docs.sympy.org/latest/contributing/docstring.html
I would like to work on this issue, please assign it to me

Commit message: Update sympy/core/symbol.py

Co-authored-by: S.Y. Lee  <sylee957@gmail.com>

Patch to review:
diff --git a/sympy/core/symbol.py b/sympy/core/symbol.py
index 68c89874c97f..4e5c754fff32 100644
--- a/sympy/core/symbol.py
+++ b/sympy/core/symbol.py
@@ -205,21 +205,56 @@ def numbered_string_incr(s, start=0):
 
 class Symbol(AtomicExpr, Boolean):
     """
+    Symbol class is used to create symbolic variables.
+
+    Explanation
+    ===========
+
+    Symbolic variables are placeholders for mathematical symbols that can represent numbers, constants, or any other mathematical entities. A symbolic variable, created using the 'Symbol' class, can be used in mathematical expressions and perform symbolic computations.
+
     Assumptions:
-       commutative = True
+
+    commutative = True
+    positive = True
+    real = True
+    imaginary = True
+    complex = True
+    complete list of more assumptions- :ref:`predicates`
 
     You can override the default assumptions in the constructor.
 
     Examples
     ========
 
-    >>> from sympy import symbols
-    >>> A,B = symbols('A,B', commutative = False)
-    >>> bool(A*B != B*A)
-    True
-    >>> bool(A*B*2 == 2*A*B) == True # multiplication by scalars is commutative
+    >>> from sympy import Symbol
+    >>> from sympy.abc import x
+    >>> x = Symbol("x", positive=True)
+    >>> x.is_positive
     True
+    >>> x.is_negative
+    False
+
+    passing in greek letters:
+
+        >>> from sympy import Symbol
+        >>> alpha = Symbol('alpha')
+        >>> alpha
+        α 
+
+    Trailing digits are automatically treated like subscripts of what precedes them in the name.
+    General format to add subscript to a symbol :
+    ``<var_name> = Symbol('<symbol_name>_<subscript>')``
+
+        >>> from sympy import Symbol
+        >>> alpha_i = Symbol('alpha_i')
+        >>> alpha_i
+        αᵢ
+
+    Parameters
+    ==========
 
+    AtomicExpr: variable name
+    Boolean: Assumption with a boolean value(True or False)
     """
 
     is_comparable = False


Code review comments:
diff_hunk: @@ -205,21 +205,56 @@ def numbered_string_incr(s, start=0):
 
 class Symbol(AtomicExpr, Boolean):
     """
+    Symbol class is used to create symbolic variables.
+
+    Explanation
+    ===========
+
+    Symbolic variables are placeholders for mathematical symbols that can represent numbers, constants, or any other mathematical entities. A symbolic variable, created using the 'Symbol' class, can be used in mathematical expressions and perform symbolic computations.
path: sympy/core/symbol.py
text: @user1:
Unfortunately, I think that we need better prompt to explain symbols, 
because the definition just seems like cyclic 

> **Symbolic** variables are placeholders for mathematical **symbols**

@author:
Ok👍