Tracking issue for Commenting eudplib

[zuhanit]

• [ ] Comment eudplib.core module
• [ ] Comment eudplib.utils module
• [ ] Comment eudplib.trigger module
• [ ] Comment eudplib.epscript module
• [ ] Comment eudplib.ctrlstru module
• [ ] Comment eudplib.memio module
• [ ] Comment eudplib.collections module
• [ ] Comment eudplib.scdata module
  • https://github.com/armoha/euddraft/issues/134
• [ ] Comment eudplib.string module
• [ ] Comment eudplib.eudlib module
• [ ] Comment eudplib.qgc module
• [ ] Comment eudplib.maprw module
• [ ] Comment eudplib.trigtrg module

---

ORIGINAL ISSUE FOLLOWS:

Commenting eudplib

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

• What function or class do
• Simple usage

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]

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]

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

[zuhanit]

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]

@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]

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

[zuhanit]

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]

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]

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]

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