Is there something similar to jsdoc for python?

Ideas
1

Hi all!

1. Proposal

  1. “Generally developers believe that you need TypeScript or Flow if you want type safety for JavaScript. This article we will explore a third alternative to achieve those same goals using just JSDoc comments and Visual Studio Code as your editor. Technically, we are going to use TypeScript but not for compiling our code. Instead we’ll use it to check the types of our JavaScript code during code time using JSDocs comments and type inference.” - reference
  2. I would like to have a jsdoc for python to specify in the comments the types I will use in python functions. So… I call this “semantic poo in def in python”… it’s similar to jsdoc
  3. Keywords are: static, private, private, void, public, string, int, float, boolean in def or comments in def as:

2. The problems to be solved

  1. The current problem I would like to solve is legacy applications, old applications made in Java that I would like to migrate to Python.
  2. This issue can help Java developers who want to migrate Java applications to Python for a specific reason.

3. rules

3.1 - Case 1: keyword def(…): # // code to be executed …

# Main or myMethod with: static|private|public|void
static def functionName(parameters): # // code to be executed ...
private def functionName(parameters): # // code to be executed ...
void def functionName(parameters): # // code to be executed ...
public def functionName(parameters): # // code to be executed ...

3.2 - Case 2: keyword def(…): # // code to be executed …

# Main or myMethod with: string|int|float|boolan
string def functionName(parameters): # // code to be executed ...
float def functionName(parameters): # // code to be executed ...
int def functionName(parameters): # // code to be executed ...
boolean def functionName(parameters): # // code to be executed ...

3.4 - Case 3: @type in “pydoc similar to jsdoc” def(…): # // code to be executed …

3.4.1 - case 1: case1.py

# @type def {public} and parameter{void} 
def public Main():
  #@type def {static, int} and parameter{int, int}
  def static int myMethod(int x, int y):
  	return x + y

  # @type def {public, static, void} and parameter{args:any} 
  def public static void main(args*):
  	print(myMethod(5, 3))
  
print(Main()) # Outputs 8 (5 + 3)

3.4.2 - case 2: case2.py

def public Main():
	def static int myMethod(int x):
		return 5 + x

	def public static void main(args*):
		print(myMethod(3))

print(Main()) # Outputs 8 (5 + 3)

3.4.3 - case 3: case3.py

# @type def {public} and parameter{void} 
def public Main():

  # @type def {static, void} and parameters{age: int} name A name to use.
  # Create a checkAge() method with an integer variable called age
  def static void checkAge(int age):

    # If age is less than 18, print "access denied"
    if (age < 18): print("Access denied - You are not old enough!")
    
    # If age is greater than, or equal to, 18, print "access granted"
    else: print("Access granted - You are old enough!");

  def public static void main(args*):
  	checkAge(20) #Call the checkAge method and pass along an age of 20

# Outputs "Access granted - You are old enough!"
Main()

4. Reasons

  1. Bringing Java Developers together in Python, Python is an amazing language, but many Java developers I know have difficulty programming in Python because it is something very different from what they are used to doing.
  2. I’m a Java developer and when I met Python I fell in love
  3. Pydoc would be to help specify the types in the def like jsdoc in Typescript
  4. This could help Java developers like Javascript to migrate to Python
  5. There are many legacy applications that I would like to easily migrate to Python… This could be done if there was a pydoc for it as specified here

5. Notes

  1. What do you guys think of the idea?
  2. I would like positive and negative feedbacks
  3. My intention is to help the Python community and the Java and Javascript community

6. Why is this interesting?

  1. It is much easier to create modules and functions with Python than with classes.
  2. Creating classes is something that I believe is much more complex than creating modules and functions. In part because modules and functions are independent.
  3. Microsoft created a language called F# that is made for object programming and not object-oriented programming.
  4. What I’m proposing here is object programming. Which is partially done with functions and modules. With “pydoc” we can have object programming which in my opinion is “better than object-oriented programming”.

7. References

2

Perhaps you could look at Sphinx?

https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html

Docstrings (PEP 257) are also used, in a variety of formats (reST, Numpydoc, Google, etc).

The syntax you are using in your examples is illegal in Python, by the way.

A

1 Like
3

@AA-Turner Hi! Thank you for feedback!

  1. Yes, I know!
  2. My idea was to have this syntax.
  3. If it’s not possible to have this syntax I’m proposing, my goal would be to have comments to make this possible as Jsdoc… but as “pydoc”
4

Python already has a rich typing and type-checking system, why can be enforced by command-line tools (eg MyPy) or IDEs (eg PyCharm, or plugins). PyCharm especially supports (Google-, NumPy- and Sphinx-style) doc-string parsing.

What’s the purpose of the static keyword? Also, you can achieve private naming by prefixing a single underscore (by convention).

In my experience, when switching between C-syntax languages (like Python, Java and JavaScript) learning the new syntax isn’t the hard part, rather it’s the libraries and language model.

2 Likes
5

For static type annotations in Python, see PEP 484, and for type checking, see e.g. Mypy or one of the other popular type checkers.

Let’s take your example:

A “literal” translation to syntactically correct (though not semantically idiomatic) Python, including type annotations, would be something like:

from typing import Any

class Main():
    @staticmethod
    def __my_method(x: int, y: int) -> int:
        return x + y

    @classmethod
    def main(cls, *args: Any) -> None:
        print(cls.__my_method(5, 3))
  
Main.main()  # Prints 8 (5 + 3)

However, while a literal translation of what the presumably equivalent Java code would do, in Python there’s usually little reason to use static methods as opposed to just module-level functions, nor a Main() class to run your program, nor static classes. Here’s a more Pythonic equivalent:

def _my_function(x: int, y: int) -> int:
    return x + y

def main() -> None:
    print(_my_function(5, 3))

if __name__ == "__main__":
    main()  # Prints 8 (5 + 3)
2 Likes