Document the code . . . [#232520]

It would be nice if the functions were completely documented. For example, the mimemail() function, takes up to nine parameters, but has no documentation about what those parameters take nor about the return value it provides. I've just been using the small amount of documentation for mimemail_prepare(), but it's certainly not clear that the information is the same, and it only has six of it's nine parameters documented. In trying to figure out how to handle attachments, for example, it was a lot of trial & error and printing variables to the screen until things started working correctly.

Comment	File	Size	Author
#5	mimemail.documentation.patch	6.78 KB	jerdavis
#4	mimemail.module.documentation.patch	8.57 KB	oadaeh

Comments

Comment #1

allie micka

she/her

commented 10 March 2008 at 20:32

You're right, that would be super-nice!

I accept patches ;)

Comment #2

oadaeh commented 10 March 2008 at 22:12

Yes, I've heard that. The problem is that I have to first learn how the code works before I can document it. You already know it, so it would be much easier and quicker for you than for me.

Comment #3

allie micka

she/her

commented 10 March 2008 at 22:23

I understand and respect your stance and I'm not trying to be flip. However, this work is not funded, and I'm spread pretty thin as it is.

Partial patches are also welcome ( e.g. just one function, or some documentation on an area that has tripped you up ).

Thanks!

Comment #4

oadaeh commented 16 April 2008 at 20:20

Status:

Active

» Needs review

Status	File	Size
new	mimemail.module.documentation.patch	8.57 KB

Here is my first take on documenting the mimemail.module file. There are a couple of functions I don't totally have my head around, so there may be some inaccuracies. The documentation formatting is based on the Doxygen formatting conventions page. I also tried really hard to not mess with any of the code (removing spaces, etc.), to avoid mixing causes.