diff --git a/docs/todo.md b/docs/todo.md deleted file mode 100644 index d5b194c..0000000 --- a/docs/todo.md +++ /dev/null @@ -1,106 +0,0 @@ -# todo - -**Filetype:** _MATLAB® script_ - -**Synopsis:** _TODO_ - -1. Parsing functions' and methods' arguments blocks to enable auto-documenting of -input constraints (size, type, validation functions) and default assignments. -(for defaults, it might be more sensible generally to copy the assignment -portion of the code itself (e.g. "= zeros(100,100)") rather than the value itself.) - - -Probably not difficult to do! - This simple [code search][https://www.mathworks.com/matlabcentral/answers/101485-how-do-i-find-a-file-containing-a-particular-string-in-a-given-directory-in-matlab-7-13-r2011b] - described could be a useful starting point. - An even simpler option is probably just to use `type( filename )` - - Notes: - - (See related item (9?) down the list re: adding the option to include - implementation details in the documentation) - - - nargin and nargout are readily obtained for functions + methods, but - getting the remaining details will require something more involved (e.g. - parse return from a call to MATLAB's TEXTSCAN()) - (probably not that difficult given the arguments block needs to fall between - the leading documentation comments and the beginning of the function code.) - - - MATLAB meta.class objects provide a lot of useful material to document - classes and their members. E.g.: - ``` - Mc = meta.class.fromName( 'Documentor' ) ; - ``` - Mc.MethodList will then contain info on Documentor's methods -- including - the input names (counting them then gives the number of arguments). - Curiously however, it seems that if you add an arguments block to a class - method---even if you don't specify default values, which normally renders - arguments optional---suddenly the Input names disappear and are replaced by - an uninformative 'varargin'?? - - It generally seems that the whole MATLAB meta.class library isn't - fully/coherently implemented. (e.g. many properties that sound as though - they would be very useful (e.g. Descrition, DetailedDescription) are not - currently used (according to their own documentation - - Further, if you convert call - ``` - struct( Mc.MethodsList ) - ``` - hidden properties are displayed (e.g. InputTypes) that clearly haven't been - implemented (e.g InputTypes always seems to be {'any'} even when an - arguments block clearly states what is permissible) - -2. Make (or identify existing) templates for .m files to facilitate -auto-documentation (i.e. standard formating for help section of scripts, -functions, classes + class members). E.g. Should there be typically sections -like ### Summary ###, ### Inputs ###, ### References ###, etc.? - -3. Configure the output format for documentation (typesetting, indentation, etc.) - e.g. what should generally be emboldened? italicized? - -4. Function to write or modify a mkdocs.yml configuration file according to -new documentation file/directory structure - -5. Source control (git) + host (e.g. readthedocs) integration: - when/when not to rebuild doc files and push? - -6. Adding+formatting - - - Handing differences between Matlab markup and Markdown syntaxes? - - - Adding hyperlinks in the documentation to the corresponding code on github? - Is this something readthedocs can do automatically? If the file structure - is kept the same (i.e. doc directory tree mirrors that of the code) this - should be straightforward? - - Decide among the approaches listed here which one would be easiest to use : - - -7. Git organization: e.g. make helpMeDoc a package in a separate repo in NeuroPoly and - include as a 'submodule' in realtime_shimming? It's not specific to the - shim project and---while the world waits for MathWorks to provide this sort - of functionality---it could probably be useful to others - -8. Unit testing? - -9. Incorporating options generally into the documentation process (e.g. as a -parameters struct input to Documentor(), a configurable text file, or -something else). As it stands, Documentor will include pretty much all the -available info; however, having the option of simplified 'user' documentation -would likely be useful. - -- Adding option (perhaps as a logical called "isGeneratingOverview") to -generate an overview/table of contents file, consisting of the code names -and the summary header line (i.e. from Examiner.Attributes.Description). -This might be similar to MATLAB's Contents.m files, or the displayed return -from LOOKFOR (e.g. type: lookfor image) e.g. - - -- Adding the option of including implementation details in the -documentation? e.g. what internal calls to custom (or matlab) functions are -made in a given piece of code? (e.g. see -) - -10. if/when it becomes presentable, replace the example link in the Documentor.m -description to the github page or readthedocs page with a link to the complete -documentation for the entire helpDocMd code library - diff --git a/src/todo.m b/src/todo.m deleted file mode 100644 index 39924cd..0000000 --- a/src/todo.m +++ /dev/null @@ -1,101 +0,0 @@ -% TODO -% -% 1. Parsing functions' and methods' arguments blocks to enable auto-documenting of -% input constraints (size, type, validation functions) and default assignments. -% (for defaults, it might be more sensible generally to copy the assignment -% portion of the code itself (e.g. "= zeros(100,100)") rather than the value itself.) -% -% -Probably not difficult to do! -% This simple [code search][https://www.mathworks.com/matlabcentral/answers/101485-how-do-i-find-a-file-containing-a-particular-string-in-a-given-directory-in-matlab-7-13-r2011b] -% described could be a useful starting point. -% An even simpler option is probably just to use `type( filename )` -% -% Notes: -% - (See related item (9?) down the list re: adding the option to include -% implementation details in the documentation) -% -% - nargin and nargout are readily obtained for functions + methods, but -% getting the remaining details will require something more involved (e.g. -% parse return from a call to MATLAB's TEXTSCAN()) -% (probably not that difficult given the arguments block needs to fall between -% the leading documentation comments and the beginning of the function code.) -% -% - MATLAB meta.class objects provide a lot of useful material to document -% classes and their members. E.g.: -% ``` -% Mc = meta.class.fromName( 'Documentor' ) ; -% ``` -% Mc.MethodList will then contain info on Documentor's methods -- including -% the input names (counting them then gives the number of arguments). -% Curiously however, it seems that if you add an arguments block to a class -% method---even if you don't specify default values, which normally renders -% arguments optional---suddenly the Input names disappear and are replaced by -% an uninformative 'varargin'?? -% -% It generally seems that the whole MATLAB meta.class library isn't -% fully/coherently implemented. (e.g. many properties that sound as though -% they would be very useful (e.g. Descrition, DetailedDescription) are not -% currently used (according to their own documentation -% -% Further, if you convert call -% ``` -% struct( Mc.MethodsList ) -% ``` -% hidden properties are displayed (e.g. InputTypes) that clearly haven't been -% implemented (e.g InputTypes always seems to be {'any'} even when an -% arguments block clearly states what is permissible) -% -% 2. Make (or identify existing) templates for .m files to facilitate -% auto-documentation (i.e. standard formating for help section of scripts, -% functions, classes + class members). E.g. Should there be typically sections -% like ### Summary ###, ### Inputs ###, ### References ###, etc.? -% -% 3. Configure the output format for documentation (typesetting, indentation, etc.) -% e.g. what should generally be emboldened? italicized? -% -% 4. Function to write or modify a mkdocs.yml configuration file according to -% new documentation file/directory structure -% -% 5. Source control (git) + host (e.g. readthedocs) integration: -% when/when not to rebuild doc files and push? -% -% 6. Adding+formatting -% -% - Handing differences between Matlab markup and Markdown syntaxes? -% -% - Adding hyperlinks in the documentation to the corresponding code on github? -% Is this something readthedocs can do automatically? If the file structure -% is kept the same (i.e. doc directory tree mirrors that of the code) this -% should be straightforward? -% -% Decide among the approaches listed here which one would be easiest to use : -% -% -% 7. Git organization: e.g. make helpMeDoc a package in a separate repo in NeuroPoly and -% include as a 'submodule' in realtime_shimming? It's not specific to the -% shim project and---while the world waits for MathWorks to provide this sort -% of functionality---it could probably be useful to others -% -% 8. Unit testing? -% -% 9. Incorporating options generally into the documentation process (e.g. as a -% parameters struct input to Documentor(), a configurable text file, or -% something else). As it stands, Documentor will include pretty much all the -% available info; however, having the option of simplified 'user' documentation -% would likely be useful. -% -% - Adding option (perhaps as a logical called "isGeneratingOverview") to -% generate an overview/table of contents file, consisting of the code names -% and the summary header line (i.e. from Examiner.Attributes.Description). -% This might be similar to MATLAB's Contents.m files, or the displayed return -% from LOOKFOR (e.g. type: lookfor image) e.g. -% -% -% - Adding the option of including implementation details in the -% documentation? e.g. what internal calls to custom (or matlab) functions are -% made in a given piece of code? (e.g. see -% ) -% -% 10. if/when it becomes presentable, replace the example link in the Documentor.m -% description to the github page or readthedocs page with a link to the complete -% documentation for the entire helpDocMd code library