search

armoha / euddraft

System for pluginizing eudplib codes.
Other
29 stars 4 forks source link

Tracking issue for Commenting eudplib #71

Open zuhanit opened 2 years ago

zuhanit commented 2 years ago

Commenting eudplib

It's important to commenting eudplib to easily understood by others.

But how can it be? Do we have to make a style to commenting eudplib? How can we check comment provides correct information?

Reference

https://peps.python.org/pep-0257

armoha commented 2 years ago

UnitGroup documentation: https://github.com/armoha/eudplib/blob/96d727f1310141da4931d2d64af77ffb64275a3a/eudplib/eudlib/unitgroup.py#L87

Q. Is current documentation satisfying?

Not sure. .cploop is inherently hard to understand. There is no detailed documentation on each methods/properties (UnitGroup.add(epd), unit.remove(), unit.dying block, unit.epd, unit.move_cp(epdoffset), unit.set_cp(epdoffset))

Given the majority of Korean end users, localization support is highly desirable. We already localize error messages but I don't know if it is possible to generate localized python documentation and comments.

armoha commented 2 years ago

Listing undocumented functions would be first step. Related issue: armoha/euddraft#49

zuhanit commented 2 years ago

UnitGroup documentation: https://github.com/armoha/eudplib/blob/96d727f1310141da4931d2d64af77ffb64275a3a/eudplib/eudlib/unitgroup.py#L87

Q. Is current documentation satisfying?

Not sure. .cploop is inherently hard to understand. There is no detailed documentation on each methods/properties (UnitGroup.add(epd), unit.remove(), unit.dying block, unit.epd, unit.move_cp(epdoffset), unit.set_cp(epdoffset))

Given the majority of Korean end users, localization support is highly desirable. We already localize error messages but I don't know if it is possible to generate localized python documentation and comments.

Sphinx supports internationalization. If documentation generated by sphinx as you mentioned, it's pretty easy to do that, even it takes some effort.

armoha commented 2 years ago

@zuhanit For comments, I think comments of standard library should only be in single locale. It would be ugly and not helpful if user went to definition and see comments in various languages like #ko-KR 유닛그룹 #en-US UnitGroup #zh-CN 单位集团 would be suboptimal. Best user experience would be only display single comments based on user configuration, and display suggestion and diagnostics as same as how Visual Studio works.

Using gettext on docstrings: https://stackoverflow.com/questions/27214065/how-to-docstring-in-python-for-multiple-languages

armoha commented 2 years ago

Swift has code comment and string literal localization feature: https://developer.apple.com/documentation/swift-playgrounds/localizing-code-comments-and-string-literals

zuhanit commented 2 years ago

I'm taking a glance at pyright for detailed implements how it provides intellisense. I think there's no options for localize intellisense maybe :(

armoha commented 2 years ago

I'm taking a glance at pyright for detailed implements how it provides intellisense. I think there's no options for localize intellisense maybe :(

https://github.com/microsoft/pyright/blob/main/packages/pyright-internal/src/localization/localize.ts

zuhanit commented 2 years ago

I'm taking a glance at pyright for detailed implements how it provides intellisense. I think there's no options for localize intellisense maybe :(

https://github.com/microsoft/pyright/blob/main/packages/pyright-internal/src/localization/localize.ts

Does it used for translate docstring?

armoha commented 1 year ago

Commenting and typing would be great to apply mypyc and get performance gain: #89

armoha commented 3 days ago

https://sphinxcontrib-napoleon.readthedocs.io/en/latest/ https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google

In my view, ReST style docstrings can be quite dense and challenging to read, particularly when it comes to documenting parameters and return values. On the other hand, Google style docstrings are more visually accessible and well-organized. Additionally, the Google style format is compatible with the Napoleon text preprocessor for Sphinx, making it a preferred choice for clarity and ease of use.

armoha commented 3 days ago

https://github.com/armoha/eudplib/blob/a81219379e355dba8f3396b837aedcb417af8d0b/eudplib/scdata/unit.py#L134-L190

This example demonstrates how to document some members of the TrgUnit class using Google style Python docstrings. The docstrings for descriptors follow a format similar to module-level variables, including a one-line summary in English and adhering to PEP 224.