Some suggestions

Question

Some suggestions

crazyguitar opened this issue 7 years ago · 7 comments

crazyguitar commented 7 years ago

suggestions from feedback

Answer 1 · 2018-12-04T08:39:01.000Z

Can i contribute even I'm still novice but i want to learn more

Thank you

Answer 2 · 2018-12-04T14:35:19.000Z

Sure! Any contributions are welcome! You can send pull requests in this project if you have any idea.

Answer 3 · 2019-01-18T10:00:41.000Z

I stumbled into your project when I was looking for how to correctly doc. my Python C extensions. Nice , that there is even a separate subject Doc String. Too sad, that it lacks how arguments are documented. Actually, I was looking for how to doc. possibly raised exceptions. (I just implemented a vector.normalize() and it may raise a RuntimeError if vector is too short. - I thought it would be worth to tell Python programmers about this.) ;-)

Answer 4 · 2019-01-18T15:21:16.000Z

Hi @scheff173

You mean this project can add some info about the detail of document string in C?

For example (from PEP 7)

#ifndef PyDoc_STR
#define PyDoc_VAR(name)         static char name[]
#define PyDoc_STR(str)          (str)
#define PyDoc_STRVAR(name, str) PyDoc_VAR(name) = PyDoc_STR(str)
#endif

Answer 5 · 2019-01-18T18:40:14.000Z

Hello, My comment was about how to format the doc. text itself. I believe there is a certain doc. format because `help()` accesses the doc. strings as well as external doc. tools (which, I must admit, I've never checked out - not yet). The style guide in [PEP 7](https://www.python.org/dev/peps/pep-0007/#documentation-strings) looks as short as your doc. (just a statement - no offense) I could swear we once found one where at least function arguments where mentioned as well. This could look e.g. like this: static PyMethodDef functions[] = { { "degToRad", &degToRad, METH_VARARGS, "rf.degToRad(angle) -> float\n" "converts a value in degree to the value in radians.\n\n" "Arguments:\n" "angle -- the angle in degree (float)\n" }, { "radToDeg", &radToDeg, METH_VARARGS, "rf.radToDeg(angle) -> float\n" "converts a value in radians to the value in degrees.\n\n" "Arguments:\n" "angle -- the angle in radians (float)\n" }, nullptr }; If I only could remember where I saw this. I will google again and let you know if I find something (may be, on weekend - week in office is near over on my side). ;-) Thanks for your immediate reply & have a nice weekend, Dirk.

Answer 6 · 2019-01-19T13:24:45.000Z

I googled a while to find something authoritative concerning how text of doc. strings should be formatted. This is what I found:

PEP 287 -- reStructuredText Docstring Format

When plaintext hasn't been expressive enough for inline documentation, Python programmers have sought out a format for docstrings. This PEP proposes that the reStructuredText markup
PEP 256 -- Docstring Processing System Framework arised this topic (giving a motivation to use some kind of mark-up language for doc. which allows further post-processing) and leaded me finally to...
PEP 257 -- Docstring Conventions
which I consider as most valuable hit with short explanation and some small examples.

Answer 7 · 2019-01-20T04:37:00.000Z

@scheff173

oh! I see. You recommend that this project can add some snippets to guide how to document the Python code, right?

Issue #80 will handle this. Sorry, I am so too recently. I will update this issue soon.

By the way, if you want to know how to write a doc in your C extension, you can refer to socket.c. Actually, I learned a lot of thing from CPython source code. 😃