Garbage collector documentation #1230
Conversation
|
Also, in I am getting this failure in both master and my branch. |
|
Changes Unknown when pulling 50ba431 on cloudformdesign:gc_doc into * on micropython:master*. |
|
I just realized that this doesn't apply to the "standard" way to document. Does upython have a "stanard" documentation? Have you thought about standardizing on doxygen? I (try to) follow the contiki documenting style, which follows doxygen. Have you thought about using this? If there is no standard, I would suggest it as a good template: https://github.com/contiki-os/contiki/blob/master/doc/code-style.c |
|
I thought I saw comment style being mentioned once but I cannot find it anymore and it's also not in https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md so it's definitely worth some discussion. I do think doxygen is interesting but I'd prefer something simpler instead of the particular style used here, main reason being this style is too hard to maintain: one needs x amount of indentation and y amount of dashes. Every commit with a comment would have to be carefully reviewed to check if the style matches, that is a waste of time. It is also not clear to me when those dashed lines should be used, nor why you chose to sometimes terminate comments ( You should probably generate the documentation once as well: some comments might not be placed where you actually want them. For example comment Apart from that: nice effort and certainly interesting for people just starting to look into the code. |
|
Sorry, I don't see much of "documentation" here, more like personal notes. Perhaps, the original idea to put in wiki is better? Here's discussion on related topic: http://stackoverflow.com/questions/167498/what-is-less-annoying-no-source-code-documentation-or-bad-code-documentation |
|
@pfalcon Well, that discussion says:
and
All reasons why I wanted feedback on it. If you think it should be more brief and less descriptive I can try to do that, but I agree with the poster that "method, class, etc summaries are mandatory" -- and this module has no summaries. I also agree that speculative documentation (that is marked as such) is often better than no documentation. |
|
The I agree that doxygen is pretty picky, and I didn't realize about the autobrief -- I think your comments are accurate. If I had to choose, I would make the commenting as such: */----------------------------------------------
8000
------------------------------*/
/**
* This is the documentation for a function or structure. This
* first line should contain a short description
*
* There should be a space between the first description
* and the rest of the description. Use this space to comment
* on the code.
*
* \param1 name comment on parameters like this
* \retval comment on the return value like this
*/
int function(char *name){
...
return 5;
} |
It should be brief and descriptive, avoid "original research" in roughly wikipedia terms, like telling that allocation table is "allocator" (it is not), avoid providing trivial info like where something is defined (figuring that out is a basic skill, if something changes, your "documentation" is false), or that function which is named verify verifies, avoid providing repetitive info (something is member, member, member), etc. - all the things you read on http://thedailywtf.com/ and in other places.
The guy who said that is likely a big boss who does a payroll, so he knows what he's talking about. It's all simpler with open-source - documentation has lower priority, because functionality has higher and resources are usually rather limited. And in this situation, providing bad documentation is worse than providing better code. And if you know big boss guy who wants to sponsor writing docstrings for every piece of method - do let everyone know. (Just please don't tell that you're going to write doxygen docs for every function in uPy (possible) and maintain them (impossible)). |
So, my feedback: I agree that this module lacks summary, it's worth saying that it provides simple conservative tracing garbage collector and link to wikipedia article. Otherwise, you started a wiki page https://github.com/micropython/micropython/wiki/Memory-Manager , please do maintain it as your understanding of inner working progresses. As usual, it's just my opinion. |
The standard is implicit in the format of existing comments: be concise, use In general I'm against lengthy and unnecessary comments, and I don't want to go down the doxygen route. Reading the code should be enough to describe what's happening, and, if it's not, then you write a comment. Most of the comments in this PR go against the above rules. There are some comments that you have that are worth adding but they need trimming and re-formatting. |
Translate strings in nrf directory
This is to prepare for #1168. I would appreciate any comments on this documentation before I continue with making it apply to standard malloc/free.
Also, I am considering implementing a standard NEXT macro that gets the next piece of allocated memory -- this way the entire memory can easily be stepped through. All micro memory allocators that I have encountered (including tinymem) support this, so I think it should be a requirement for any memory manager that micro-python plugs into.
In addition, I think any memory manager we plug into should be able to do in-place marking of memory -- something that is also not necessarily supported with standard malloc/free.
Both of these requirements will increase the speed and reduce the memory consumption (and complexity) of any memory manager used by micropython.