Your are right, the documentation is very incomplete. We have started taking various notes throughout the porting process. It may have been too early to publish. As of the correct place for the wiki, somehow I had the impression that the github wiki contains nothing close to what I have been looking for while the main wiki did. My bad. I have removed the notes from the main wiki now.pfalcon wrote:There're both Developers' and Users' wiki, and I would say that their breakdown and location is quite logical: Github, which hosts source code, also hosts Developers' wiki: https://github.com/micropython/micropython/wiki . http://www.micropython.org, which is user-facing site, hosts Users' wiki.braiins wrote: We have started a wiki page: http://wiki.micropython.org/Developers/PortingNotes that covers topics that we had to go through while working on the port for FreeRTOS. The reason is that I haven't found any developer related documentation except for this forum. It is a work-in-progress, I will be adding elements throught the development process.
One of the problem of wiki is incomplete and/or stale content. Let me give an example from your page:
mp_obj_t
All Micro Python objects can be casted to this type (effectively void *)
Your also right about incorrect documentation being worse than no documentation. The main problem that I see is that there is no place that documents the big picture. The documentation in the source code is usually sufficient. I have also incorporated your notes on mp_obj_t into the wiki page. The new place for the notes is our clone of the devel wiki at: https://github.com/braiins/micropython/ ... ting-Notes. The version tracking will be done by github. I will keep the original wiki history just in case the developer notes every mature enough to consider merging it into the main github wiki.pfalcon wrote:This isn't true. mp_obj_t is an opaque type, defined as not compatible with any other type, and requiring MP_OBJ_FROM_PTR(), MP_OBJ_TO_PTR() macros to be accessed. Historically, it was defined as void*, and some ports still use shortcuts to access it, but it's no longer correct as of now. Regarding "outdated" part, see a page I created during my initial code acquaintance: https://github.com/micropython/micropyt ... /Internals . It wasn't edited for 2 years now, so can be expected to contain stale material now, and warns about that (surprisingly, what's written there still holds, but only because there's just couple of facts listed on that page).
Development documentation is very important, but incorrect documentation is worse than no documentation (in which case interested parties will go straight to the source code, and find it pretty well commented/documented, suggestions for improvements in that area are welcome). So, we encourage content like above (http://wiki.micropython.org/Developers/PortingNotes) to be posted as a 3rd-party blog post, to separate it from official information of MicroPython project, and specify exact version of MicroPython it was written against (blog engine should timestamp the post itself to complete the temporal references).
Thank you for your response and valuable inputs.
Cheers,
Jan