libmir/mir-stat

Documentation Issues

jmh530 opened this issue · 8 comments

jmh530 commented

I'm seeing some issues with the documentation. Most of them I'm not sure on the best way to fix.

  1. Sometimes the unittests are mixed in between the function definitions. For instance, it will have the initial definitions and then some unittests and then some more definitions at the end. See interquartileRange as an example of this, but it happens in several places.

  2. There seems to be some kind of issue with new lines. For instance, I don't see an issue when text is separated by a blank line, but when there is no blank line, then they can be put together onto one line. For instance, the kurtosis documentation for parameters has summation grouped together with kurtosisAlgo. Alternately, for zscore, the first line of the concatenates two separate lines, whereas the code here has them on different lines (but without a blank line separating them).

  3. Something is screwed up on the QuantileAlgo table. Probably my fault...

  4. Quantile unittests are missing. From here, it's not as if they are missing the documentation ///. The issue is likely resolved by moving quantileImpl from coming between them.

9il commented
  • Something is screwed up on the QuantileAlgo table. Probably my fault...

Just needs $T3, a8254e4

4. Quantile unittests are missing. From here, it's not as if they are missing the documentation ///. The issue is likely resolved by moving quantileImpl from coming between them.

Yes, this is because the unittest is associated with the last API member before them.

There seems to be some kind of issue with new lines. For instance, I don't see an issue when text is separated by a blank line, but when there is no blank line, then they can be put together onto one line. For instance, the kurtosis documentation for parameters has summation grouped together with kurtosisAlgo. Alternately, for zscore, the first line of the concatenates two separate lines, whereas the code here has them on different lines (but without a blank line separating them).

Maybe it would be better to split some unittest lines directly in the code.

Sometimes the unittests are mixed in between the function definitions. For instance, it will have the initial definitions and then some unittests and then some more definitions at the end. See interquartileRange as an example of this, but it happens in several places.

Because the unittests are assigned to the outer template definition, it goes first, then its unittest, and then its inner API and then inner API unittests. This is how DDOC documentation is generated by the compiler.

jmh530 commented

@9il I'm not sure I understand what you mean by "Maybe it would be better to split some unittest lines directly in the code."

I've noticed the issue with template parameters being mushed together in the normal mir documentation too, but I've also figured out the cause of the problem. I was using : where I should have used =. I will submit fixes.

More generally, I've never tried to generate the mir documentation locally. Do you just pass -D to the compiler? If it's more complicated than that, then you might consider putting instructions somewhere.

jmh530 commented

@9il Where you say "Because the unittests are assigned to the outer template definition, it goes first, then its unittest, and then its inner API and then inner API unittests. This is how DDOC documentation is generated by the compiler."

I tried going through phobos to find an example of the same behavior, but the closest I could find was substitute, which only has one outer template.

For interquartileRange, the documentation looks like it lists all outer templates, then the unittests, then the inner API of the first template, then it ignores the inner API of other templates.

jmh530 commented

I filed a bug report related to function definitions getting skipped. I can't help but think that is a DDOC problem.

jmh530 commented
  • Something is screwed up on the QuantileAlgo table. Probably my fault...

Just needs $T3, a8254e4

@9il I was able to get it looking better here, but it is repeating what is in the second column in the third. Should $T3 be something like T3=$(TR $(TDNW $(LREF $1)) $(TD $2) $(TD $3)) instead of T3=$(TR $(TDNW $(LREF $1)) $(TD $2) $(TD $+))?

I know that ardrdox has $(MATH ...) to use latex. Would something like that work here? For instance, $(MATH (1 - gamma) * x_{j} + gamma * x_{j + 1}).

9il commented

I know that ardrdox has $(MATH ...) to use latex. Would something like that work here? For instance, $(MATH (1 - gamma) * x_{j} + gamma * x_{j + 1}).

Unlikely, mir is based on the dlang site.

@9il I was able to get it looking better here, but it is repeating what is in the second column in the third. Should $T3 be something like T3=$(TR $(TDNW $(LREF $1)) $(TD $2) $(TD $3)) instead of T3=$(TR $(TDNW $(LREF $1)) $(TD $2) $(TD $+))?

I will take a look

9il commented

Yes, T3=$(TR $(TDNW $(LREF $1)) $(TD $2) $(TD $3)) should work.
And maybe $(LEADINGROWN Continuous sample quantile, 3) would look better for tree columns