Some suggestions - Githubissues

crazyguitar commented 6 years ago

suggestions from feedback

heljhumenad commented 5 years ago

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

Thank you

crazyguitar commented 5 years ago

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

scheff173 commented 5 years ago

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.) ;-)

crazyguitar commented 5 years ago

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

scheff173 commented 5 years ago

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 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.

scheff173 commented 5 years ago

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.

crazyguitar commented 5 years ago

@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. 😃

crazyguitar / pysheeet

Some suggestions #46