Page 4 of 5

Re: mlib: Math Library

Posted: Thu Dec 26, 2013 6:36 pm
by Robin
davisdude wrote:I have most of it documented, except some of the newer ones, 'cause I sorta forgot... :P
Tests are not documentation. You do have some documentation in your README, but it's rather curt.

Re: mlib: Math Library

Posted: Thu Dec 26, 2013 9:04 pm
by Roland_Yonaba
Robin wrote: Tests are not documentation. You do have some documentation in your README, but it's rather curt.
Totally true. I second that. Plus, that is the reason for what I suggested LDoc. It helps parsing documentation from code comments, and also let you writeadditional documentation in a narrative style, which is awesome.
But beware, writing documentation is tedious. But in the end, it gives to the whole project a bit more of genuine and some seriousness.
And it is really helpful to the user. In doubt, no need to ask systematically a question, one can read the docs first. :megagrin:

Re: mlib: Math Library

Posted: Fri Dec 27, 2013 1:02 am
by davisdude
Robin wrote:Tests are not documentation. You do have some documentation in your README, but it's rather curt.
Oh, I thought tests were documentation. My bad.
As for the documentation, do you mind explaining how I could make it more in-depth? I thought they were pretty clear, myself (but then again, I did make them, so I know how they work...)

Not that I think that LDoc is bad or anything, it's just like it seems like it's too much to work with. I may still do it, but for now I don't think I will.

Re: mlib: Math Library

Posted: Fri Dec 27, 2013 4:35 am
by davisdude
1.9.1 is now out!
Changes:
v. 1.9.1 -Made mlib.line.closestPoint able to take either two points on the slope or the slope and intercept.
v. 1.9.0 -Added mlib.lineSegmentIntersects (no affiliation with previous one (changed to mlib.line.segment.intersect)) and mlib.line.closestPoint

Re: mlib: Math Library

Posted: Fri Dec 27, 2013 9:50 am
by Robin
davisdude wrote:As for the documentation, do you mind explaining how I could make it more in-depth?
When reading an API documentation, I want to know the following things: (bolded are the things missing)
  • The function name
  • What the function does/calculates exactly
  • When I would want to use it
  • The arguments, their description, domain, units, typical and extreme values
  • A description for the return value, its range, units, typical and extreme values
The functions in milb.stats are pretty well-documented. The ones in mlib.line and mlib.polygon rather less so. mlib.math is a mixed bag, and the documentation for mlib.circle is decent.

Re: mlib: Math Library

Posted: Fri Dec 27, 2013 3:08 pm
by davisdude
Robin wrote:When reading an API documentation, I want to know the following things: (bolded are the things missing)
  • The function name
    What the function does/calculates exactly
    When I would want to use it
    The arguments, their description, domain, units, typical and extreme values
    A description for the return value, its range, units, typical and extreme values
The functions in milb.stats are pretty well-documented. The ones in mlib.line and mlib.polygon rather less so. mlib.math is a mixed bag, and the documentation for mlib.circle is decent.
Okay, thanks. I'll get to work on that.

Re: mlib: Math Library

Posted: Sat Dec 28, 2013 12:15 am
by davisdude
Updated readme! Hopefully my documentation is more complete now!
1.9.2 is also out! I made some changes to be compatible with 0.9.0!

Re: mlib: Math Library

Posted: Sat Dec 28, 2013 9:54 pm
by davisdude
So, how's the documentation? Any better?

Re: mlib: Math Library

Posted: Sun Dec 29, 2013 5:23 pm
by Robin
The documentation is much better.

Something weird is going on here: https://github.com/davisdude/mlib#mlibmathprime-1
Was that a mistake? (Also, I doubt you often have to check if multiple numbers are prime, so the special casing seems to be a bit weird. Looking at the source code for mlib.math.prime that it is a really bad. For one thing, checking if a number is prime can trivially be done in O(sqrt(n)), but your algorithm takes O(n).)

Also, please don't double post after only ten hours, especially if you have nothing to add.

Re: mlib: Math Library

Posted: Sun Dec 29, 2013 5:41 pm
by davisdude
Robin wrote:Also, please don't double post after only ten hours, especially if you have nothing to add.
Oh, okay. Sorry.
Also: I fixedit now. After spending ~6 straight hours on it, I knew there was bound to be at least one mistake! :shock:
Also, if you don't mind, how would I decrease the amount of time taken? I didn't look up a formula, I just sort of did what made sense to me.
I don't really know of a case where you would check for multiple numbers, but just thought it would be a nice added functionality. :D