{"id":6606,"date":"2016-02-05T09:00:52","date_gmt":"2016-02-05T14:00:52","guid":{"rendered":"https:\/\/blogs.mathworks.com\/pick\/?p=6606"},"modified":"2017-08-11T13:24:43","modified_gmt":"2017-08-11T17:24:43","slug":"document-your-dependencies","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/pick\/2016\/02\/05\/document-your-dependencies\/","title":{"rendered":"Document Your Dependencies"},"content":{"rendered":"<div xmlns:mwsh=\"https:\/\/www.mathworks.com\/namespace\/mcode\/v1\/syntaxhighlight.dtd\" class=\"content\">\r\n   <introduction>\r\n      <p><a href=\"https:\/\/www.mathworks.com\/matlabcentral\/fileexchange\/authors\/32620\">Greg<\/a>'s pick this week is <a href=\"https:\/\/www.mathworks.com\/matlabcentral\/fileexchange\/25925-using-doxygen-with-matlab\">Using Doxygen with MATLAB<\/a> by <a href=\"https:\/\/www.mathworks.com\/matlabcentral\/profile\/authors\/933753-fabrice\">Fabrice<\/a>.\r\n      <\/p>\r\n      <p>Ever wanted a class dependency diagram and documentation of your MATLAB Classes. How about leveraging <a title=\"http:\/\/www.stack.nl\/~dimitri\/doxygen\/ (link no longer works)\">Doxygen<\/a> to document your development project?\r\n      <\/p>\r\n      <p>Fabrice provides a simple interface to make this possible. Interestingly enough, this entry doesn't actually contain MATLAB\r\n         Code!\r\n      <\/p>\r\n   <\/introduction>\r\n   <h3>Contents<\/h3>\r\n   <div>\r\n      <ul>\r\n         <li><a href=\"#1\">Classy Relationships<\/a><\/li>\r\n         <li><a href=\"#2\">What about the documentation?<\/a><\/li>\r\n         <li><a href=\"#3\">Documentation is already available using MATLAB<\/a><\/li>\r\n         <li><a href=\"#4\">Is this something that should be in MATLAB or Simulink?<\/a><\/li>\r\n      <\/ul>\r\n   <\/div>\r\n   <h3>Classy Relationships<a name=\"1\"><\/a><\/h3>\r\n   <p>Do you want to know how MATLAB Classes are related?<\/p>\r\n   <p>\r\n<a href=\"https:\/\/blogs.mathworks.com\/pick\/files\/inherit_graph_0.png\" rel=\"attachment wp-att-6607\"><img decoding=\"async\" src=\"https:\/\/blogs.mathworks.com\/pick\/files\/inherit_graph_0.png\" alt=\"inherit_graph_0\" width=300 class=\"alignnone wp-image-6607\" \/><\/a>      \r\n\r\n      \r\n   <\/p>\r\n   <p>The above image shows a subset of the class hierarchy for a project I have been working on, which I was able to generate using\r\n      Fabrice's tool.\r\n   <\/p>\r\n   <p>The diagram depicts each class in a box. The arrow points to the parent class from which each class is inherited.<\/p>\r\n   <p>The terminus for the dependency path is a built-in class in MATLAB, which in this case is \"handle\".<\/p>\r\n   <h3>What about the documentation?<a name=\"2\"><\/a><\/h3>\r\n   <p>If you use comments in MATLAB Code to document your functions and classes, then you need to apply Fabrice's extra convention\r\n      of \"%&gt;\" instead of just \"%\" to determine which comments get parsed by Doxygen.\r\n   <\/p>\r\n   <p>In addition Doxygen convention is the documentation for a function by default comes before the function, which the convention\r\n      in MATLAB is that it comes after the function.  To make sure your documentation is available in Doxygen and using the MATLAB\r\n      DOC function, then you likely want to consider using the \"&lt;\" flag in your first comment after a MATLAB Function or class parameter\r\n      definition.\r\n   <\/p>\r\n   <p>I did make a quick modification of the Perl script in Fabrice's entry to automate that process so that \"%&gt;\" was replaced by\r\n      \"\/\/\/&lt;\" and make the assumption that MATLAB Documentation always comes after the function or parameter definition.\r\n   <\/p>\r\n   <h3>Documentation is already available using MATLAB<a name=\"3\"><\/a><\/h3>\r\n   <p>There is already a <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2015b\/matlab\/matlab_prog\/create-help-for-classes.html#responsive_offcanvas\">documentation<\/a> mechanism available in MATLAB already. As well as the ability to <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/matlab_prog\/display-custom-documentation.html\">display custom documentation<\/a> as part of the MATLAB Documentation system.\r\n   <\/p>\r\n   <p>You can use comments in your MATLAB code to generate documentation without any additional work.  However it doesn't provide\r\n      much in the way of developing dependency graphs.\r\n   <\/p>\r\n   <h3>Is this something that should be in MATLAB or Simulink?<a name=\"4\"><\/a><\/h3>\r\n   <div>\r\n      <ul>\r\n         <li>Do you use Doxygen to document your software development projects?<\/li>\r\n         <li>Should this be a capability built into MATLAB or Simulink?<\/li>\r\n         <li>What about generated C or HDL-code?<\/li>\r\n         <li>Do you use a different method for using Doxygen with MATLAB?<\/li>\r\n      <\/ul>\r\n   <\/div>\r\n   <p>Let us know <a href=\"https:\/\/blogs.mathworks.com\/pick\/?p=6606#respond\">here<\/a>.\r\n   <\/p><script language=\"JavaScript\">\r\n<!--\r\n\r\n    function grabCode_08a97992cfd14bea861ca40dd9922767() {\r\n        \/\/ Remember the title so we can use it in the new page\r\n        title = document.title;\r\n\r\n        \/\/ Break up these strings so that their presence\r\n        \/\/ in the Javascript doesn't mess up the search for\r\n        \/\/ the MATLAB code.\r\n        t1='08a97992cfd14bea861ca40dd9922767 ' + '##### ' + 'SOURCE BEGIN' + ' #####';\r\n        t2='##### ' + 'SOURCE END' + ' #####' + ' 08a97992cfd14bea861ca40dd9922767';\r\n    \r\n        b=document.getElementsByTagName('body')[0];\r\n        i1=b.innerHTML.indexOf(t1)+t1.length;\r\n        i2=b.innerHTML.indexOf(t2);\r\n \r\n        code_string = b.innerHTML.substring(i1, i2);\r\n        code_string = code_string.replace(\/REPLACE_WITH_DASH_DASH\/g,'--');\r\n\r\n        \/\/ Use \/x3C\/g instead of the less-than character to avoid errors \r\n        \/\/ in the XML parser.\r\n        \/\/ Use '\\x26#60;' instead of '<' so that the XML parser\r\n        \/\/ doesn't go ahead and substitute the less-than character. \r\n        code_string = code_string.replace(\/\\x3C\/g, '\\x26#60;');\r\n\r\n        author = 'Greg Wolff';\r\n        copyright = 'Copyright 2016 The MathWorks, Inc.';\r\n\r\n        w = window.open();\r\n        d = w.document;\r\n        d.write('<pre>\\n');\r\n        d.write(code_string);\r\n\r\n        \/\/ Add author and copyright lines at the bottom if specified.\r\n        if ((author.length > 0) || (copyright.length > 0)) {\r\n            d.writeln('');\r\n            d.writeln('%%');\r\n            if (author.length > 0) {\r\n                d.writeln('% _' + author + '_');\r\n            }\r\n            if (copyright.length > 0) {\r\n                d.writeln('% _' + copyright + '_');\r\n            }\r\n        }\r\n\r\n        d.write('<\/pre>\\n');\r\n      \r\n      d.title = title + ' (MATLAB code)';\r\n      d.close();\r\n      }   \r\n      \r\n-->\r\n<\/script><p style=\"text-align: right; font-size: xx-small; font-weight:lighter;   font-style: italic; color: gray\"><br><a href=\"javascript:grabCode_08a97992cfd14bea861ca40dd9922767()\"><span style=\"font-size: x-small;        font-style: italic;\">Get \r\n            the MATLAB code \r\n            <noscript>(requires JavaScript)<\/noscript><\/span><\/a><br><br>\r\n      Published with MATLAB&reg; 8.6<br><\/p>\r\n<\/div>\r\n<!--\r\n08a97992cfd14bea861ca40dd9922767 ##### SOURCE BEGIN #####\r\n%% Document Your Dependencies\r\n% <https:\/\/www.mathworks.com\/matlabcentral\/fileexchange\/authors\/32620 Greg's> pick this week is\r\n% <https:\/\/www.mathworks.com\/matlabcentral\/fileexchange\/25925-using-doxygen-with-matlab Using Doxygen with MATLAB>\r\n% by\r\n% <https:\/\/www.mathworks.com\/matlabcentral\/profile\/authors\/933753-fabrice Fabrice>.\r\n% \r\n% Ever wanted a class dependency diagram and documentation of your MATLAB\r\n% Classes. How about leveraging <http:\/\/www.stack.nl\/~dimitri\/doxygen\/ Doxygen> to document your development\r\n% project?\r\n% \r\n% Fabrice provides a simple interface to make this possible. Interestingly\r\n% enough, this entry doesn't actually contain MATLAB Code!\r\n% \r\n%% Classy Relationships\r\n% Do you want to know how MATLAB Classes are related?\r\n% \r\n% <html>\r\n%   <img decoding=\"async\" src=\"inherit_graph_0.png\"\/>\r\n% <\/html>\r\n%\r\n% The above image shows a subset of the class hierarchy for a project I have been\r\n% working on, which I was able to generate using Fabrice's tool.  \r\n%\r\n% The diagram depicts each class, and the points to the parent the class\r\n% inherited from.\r\n%\r\n% The terminus for the dependency path is a built-in class in MATLAB, which in this case is \"handle\".\r\n%\r\n\r\n%% What about the documentation?\r\n% If you use comments in MATLAB Code to document your functions and\r\n% classes, then you need to apply Fabrice's extra convention of \"%>\" instead of just \"%\" to determine\r\n% which comments get parsed by Doxygen.  \r\n%\r\n% In addition Doxygen convention is\r\n% the documentation for a function by default comes before the function,\r\n% which the convention in MATLAB is that it comes after the function.  To\r\n% make sure your documentation is available in Doxygen and using the MATLAB\r\n% DOC function, then you likely want to consider using the \"<\" flag in your\r\n% first comment after a MATLAB Function or class parameter definition.\r\n%\r\n% I did make a quick modification of the Perl script in Fabrice's entry to\r\n% automate that process so that \"%>\" was replaced by \"\/\/\/<\" and make the\r\n% assumption that MATLAB Documentation always comes after the function or\r\n% parameter definition.\r\n%\r\n\r\n\r\n%% Documentation is already available using MATLAB\r\n% There is already a basic <https:\/\/www.mathworks.com\/help\/releases\/R2015b\/matlab\/matlab_prog\/create-help-for-classes.html#responsive_offcanvas documentation> mechanism available in MATLAB\r\n% already. This enables you to use comments in your MATLAB code to generate\r\n% documentation without any additional work.  However it doesn't provide\r\n% much in the way of organizing documentation or developing dependency\r\n% graphs.\r\n\r\n%% Is this something that should be in MATLAB or Simulink?\r\n% \r\n% * Do you use Doxygen to document your software development projects?\r\n% * Should this be a capability built into MATLAB or Simulink? \r\n% * What about generated C or HDL-code?\r\n% * Do you use a different method for using Doxygen with MATLAB?\r\n% \r\n% Let us know <https:\/\/blogs.mathworks.com\/pick\/ here>.\r\n\r\n##### SOURCE END ##### 08a97992cfd14bea861ca40dd9922767\r\n-->","protected":false},"excerpt":{"rendered":"<div class=\"overview-image\"><img src=\"https:\/\/blogs.mathworks.com\/pick\/files\/inherit_graph_0-1.png\" class=\"img-responsive attachment-post-thumbnail size-post-thumbnail wp-post-image\" alt=\"\" decoding=\"async\" loading=\"lazy\" \/><\/div><p>\r\n   \r\n      Greg's pick this week is Using Doxygen with MATLAB by Fabrice.\r\n      \r\n      Ever wanted a class dependency diagram and documentation of your MATLAB Classes. How about leveraging... <a class=\"read-more\" href=\"https:\/\/blogs.mathworks.com\/pick\/2016\/02\/05\/document-your-dependencies\/\">read more >><\/a><\/p>","protected":false},"author":36,"featured_media":8570,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[16],"tags":[],"_links":{"self":[{"href":"https:\/\/blogs.mathworks.com\/pick\/wp-json\/wp\/v2\/posts\/6606"}],"collection":[{"href":"https:\/\/blogs.mathworks.com\/pick\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.mathworks.com\/pick\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/pick\/wp-json\/wp\/v2\/users\/36"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/pick\/wp-json\/wp\/v2\/comments?post=6606"}],"version-history":[{"count":12,"href":"https:\/\/blogs.mathworks.com\/pick\/wp-json\/wp\/v2\/posts\/6606\/revisions"}],"predecessor-version":[{"id":8811,"href":"https:\/\/blogs.mathworks.com\/pick\/wp-json\/wp\/v2\/posts\/6606\/revisions\/8811"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/pick\/wp-json\/wp\/v2\/media\/8570"}],"wp:attachment":[{"href":"https:\/\/blogs.mathworks.com\/pick\/wp-json\/wp\/v2\/media?parent=6606"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/pick\/wp-json\/wp\/v2\/categories?post=6606"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/pick\/wp-json\/wp\/v2\/tags?post=6606"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}