Having used this package for a few days, I remain hugely impressed by it. The parser does struggle with a couple of aspects of my code though; it would be great if these could be fixed:
- It does not like Abstract in the class definition [e.g., classdef (Abstract) MyClass < MySuperClass]
- It does not like class-specific references in the Access declaration for a method [e.g., methods (Static, Access = ?MyClass)]
- It does not like quote marks around Access types [e.g., Access = 'public' ; rather than Access = public] (I'm not sure whether using quote marks is considered good or bad practice? But since both are accepted by Matlab, it would be handy if both were catered for)
(n.b., the first two things have only been valid syntax since 2012, so not really surprising that they aren't catered for, but I do use them extensively in my code, so would be great to get them working).
@Daniel. In terms of what I found daunting about installing. I guess there were two aspects. Firstly, there was compiling everything and building the dependencies. Installing all the other software in turn meant extensively updating my *very* old version of MacPorts. All the various steps took a while to download/unpack and I was convinced some link in the chain was going to break (quite a few errors were spit out along the way, but by some miracle everything worked fine in the end). To be honest none of this is the fault of this package per se, and you can't very well distribute all the third party software. But I just know quite a few people may have given up along the way. The second issue, was getting Matlab to recognise where the various dependencies (e.g., Ragel, Latex) were installed. I got a bit confused at one point, because the necessary directories were on my terminal $path, but not on Matlab's system path. I still don't really know if editing the Matlab executable was the best way to go about getting them recognised (and again, I think a lot of people would be put off doing that), but hey, it worked. Like I say, I don't think either of these things are really things you can do much about, and I think all the crucial information is in the documentation. I just think that the average Matlab user will think twice before installing this package, which is a shame since it's a really nice bit of work. (Then again, the average Matlab user probably doesn't want this package in the first place, so maybe this is a moot point.)
Oh, and have just installed it on Windows 7 too. Easy installation, working fine no problems.
I compared this with the similar fileexchange entry http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab, as well as with matlab's own built-in documenting tools.
This seems to be the best for situations such as mine, where I want to document object-oriented code spread over different packages. It is particularly forgiving in terms of how it parses comments, meaning that (after a bit of tweaking) I have comments that render well using 'help x', 'doc x', *and* which produce a beautiful doxygen html.
Installation was a little daunting and took about 30-45 mins (the supplied documentation was invaluable here). However, it was definitely worth the effort. Oh, and just for the record: I don't know if this is the best solution, but to ensure that the Matlab script could find the necessary resources, I opened /Applications/MATLAB_R2010a.app/bin/Matlab in TextEdit, and added the line "export PATH=$PATH:/usr/local/bin/:/usr/texbin" (without quotes), directly after the comments. Seemed to do the job (n.b. Mac OS X).
This is a great tool, and one which I look forward to using extensively over the coming months.
One minor observation. In terms of learning how to use it: for me personally it would have been nice if the OOP example (TestUsingTestCase.m) was much more prominent (since it seems to give best-practice), and if all the other examples were tucked away or removed altogether. I think if I'd seen TestUsingTestCase.m straight-away, it would have taken me a couple of minutes to get started. As it was it took more like 20 mins (which still isn't too bad). Maybe that's just me though.
18 Dec 2012
A MATLAB implementation of the example "How to use buttons" from the Java Tutorial.
Author: Qun HAN
Still useful and relevant. A good, simple primer on adding (J)Buttons to Matlab. Thanks
after some experiments, i think it's a doxygen trouble, because i've got the same results with C++ codes. Or it's a bad configuration of doxygen, but i tried a lot things...
I'm not sure if doxygen is able to do such a thing, but i asked them if i was mistaking. I will give you some infos when i have got some.
Maybe i'm not the only user needing this capability, and it should be great to have a special tag to remove some code from the documentation, for example "% remove this code from the documentation" and "% end of removal"
Thank you for your work,
hi, thank you for your response.
the \cond and \endcond commands work fine when they are in the description of the function.
When they are used in the code, in order to exclude some part of the code, they don't work.
Here is a simple example, where i don't want to show the lines between \cond and \endcond in the generated code.
function [c] = sumM(a,b)
% sum function
% sum function detail description.
% a : first data of type double
% b : second data of type double
% Return values:
% c : sum of a and b
c = a + b;
% dummy code to exclude from the documentation
disp('function is ok')
I think that mtoc++ should analyse wether a commented line in the code begins with some special commands. Or maybe i don't use correctly your (great !!) tool.
Thank you !
well those commands are purely doxygen-related and probably require a concurrent version; i would not expect any other difficulties with those commands in connection with mtoc++.
However, if you have reason to believe it might be caused by mtoc++, please send us some more details, logs etc.
Great job, and thank you for the last updates which make possible to include code and dependencies graphs !!
I would like now to use the special command \cond and \endcond to exclude some part of the code to the documentation.
I didn't succeded ; do you think it possible ? How should i do that ?