Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document gettext.c2py #127373

Closed
tomasr8 opened this issue Nov 28, 2024 · 6 comments
Closed

Document gettext.c2py #127373

tomasr8 opened this issue Nov 28, 2024 · 6 comments
Labels
docs Documentation in the Doc dir

Comments

@tomasr8
Copy link
Member

tomasr8 commented Nov 28, 2024

gettext.c2py is currently not documented. This function is used internally by GNUTranslations but it's also useful on its own when dealing with translations. I have a PR on the way ;)

Linked PRs

@tomasr8 tomasr8 added the docs Documentation in the Doc dir label Nov 28, 2024
@serhiy-storchaka
Copy link
Member

It is an internal function, it is not a part of the public API.

@tomasr8
Copy link
Member Author

tomasr8 commented Nov 28, 2024

It is an internal function, it is not a part of the public API.

Ah I was under the impression that anything that is not underscored is de facto a public API, documented or not. I have actually used this function before under that assumption that it was public.

So in your opinion, do you think that we should not document this function? And more generally, how I can tell if something is or is not part of the public API?

@serhiy-storchaka
Copy link
Member

It is not in __all__. Underscore is needed if __all__ is not used.

This function is not in the public API first, and all other (including the lack of documentation) is derivative.

@tomasr8
Copy link
Member Author

tomasr8 commented Nov 29, 2024

Ok thanks! I was just wondering because I sent another PR (#127348) previously which documents traceback.print_list which is also not in __all__ but there were no objections to that one 😕

@serhiy-storchaka
Copy link
Member

I am not sure about print_list, but c2py is clearly not purposed to be used by external code.

I think I already rejected a similar proposal for another gettext function. Prefixing with underscore is not required for private names, and the absence of an underscore prefix is not always a sign of a public name.

@tomasr8
Copy link
Member Author

tomasr8 commented Nov 29, 2024

Got it, thanks for the clarification!

@tomasr8 tomasr8 closed this as not planned Won't fix, can't repro, duplicate, stale Nov 29, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir
Projects
Status: Todo
Development

No branches or pull requests

2 participants