Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
This question is related to my previous one: MATLAB m-file help formatting.
What do you usually write to describe authorship of your own function? Do you put it at the end of the function body or right after the help text before any code?
How do you include version information? Is it possible to automatically update version after function modification?
This is what I usually include:
% My Name <my#email>
% My company
% Created: September 2010
% Modified: October 2010
Please share your thoughts, ideas?
I have a function in the MATLAB Central File Exchange that helps you document your function in a standard way, and works with version control software (CVS and Subversion; not git) to automatically update the author field and time of modification.
You just type new at the command prompt, then the name of the function, and it sorts out the rest.
The basic template for documentation that I use is
function [outputArgs] = TestFunction(inputArgs)
%TESTFUNCTION Summary of this function goes here
%
% [OUTPUTARGS] = TESTFUNCTION(INPUTARGS) Explain usage here
%
% Examples:
%
% Provide sample usage code here
%
% See also: List related files here
% $Author: rcotton $ $Date: 2010/10/01 18:23:52 $ $Revision: 0.1 $
% Copyright: Health and Safety Laboratory 2010
(You'll obviously want a different company in your copyright statement.)
The first line of the help documentation is known as the H1 line, and is used by the function lookfor, among others. It is important that this comes straight after the function definition line.
If you have different use cases (maybe with and without optional arguments), then you should describe each one.
The Examples: and See also: lines are formatted in a way the works with the help report generator. (I've just spotted a bug - the year should be before the company name in the copyright line. Fix on its way.)
$Author:, etc., are formatted for use with CSV/SVN. Since git uses hashes of files, you can't change the content of the file, without git thinking that it's been updated.
We keep our code in a Subversion repository and use the keywords functionality for writing this sort of information into the header comments of the m-file when it is committed to the repo. We put a block of comments right after the initial function line in (most of) our m-files.
If you are not using a source code control system then:
You really should start using one right now.
You could write a script (in Matlab, why not) for maintaining the comment information you require, and implement some process to ensure that you run the script when necessary.
We don't generally put modification dates or histories in our source files, the repository tracks changes for us. Which is another reason you should be using one.
And, while you are thinking about all this, if you haven't already done so: check out Matlab's publish functionality.
EDIT: #yuk: I guess from your mention of TortoiseSVN that you are working on Windows. It's a couple of years since I installed Subversion on my Windows PC. I don't recall any problems at all with the installation, and I'm not qualified to help you debug yours -- but there are plenty on SO who are.
As for keeping version (etc) info up to date, there's no scripting required. You simply include the special strings, such as $Rev$, which Subversion recognises as keywords in the locations in your files (probably in the comments) where you want the version information (etc). This is well explained in the Subversion Book.
As for the Matlab documentation, I think the publish (and related) features are well explained in the Desktop Tools and Development Environment handbook which is available on-line at the Mathworks web-site.
As High Performance Mark points out, some form of source code control is ideal for handling this situation. However, if you are adding information by hand here are a few pointers:
I would definitely include a line stating the MATLAB version your code was written in, or perhaps which versions you know it works for.
When adding the information, you have to leave space between it and the help comment block if you don't want to display it when the user views the help contents, like so:
function myFunction
%# Help text for function
%# Your information
Unless you do want it displayed with the help. Then just make one big comment block.
Related
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 2 years ago.
Improve this question
i'm looking to find a way to beautify my code in MATLAB. I'm talking about tabs, deleting unnecessary spaces etc., the way Eclipse does it with Ctrl+Shift+F
The smart indentation (ctrl + I) is probably all you need (as #Matteo V and #Cris Luengo already mentioned).
However, there are a few other neat tricks that you might want to have a look at if you are really into code development:
Well, first have a look at the Improve Code Readability site of MATLAB. You could use the Apply smart indenting while typing option in the Preferences > MATLAB > Editor/Debugger > Language > Indenting section (it should be turned on per default but I like the Indent all functions setting). There are a bunch of other settings that you may want to explore
If you dig yourself deeper in the MATLAB IDE, you will notice that you can adjust almost everything to your preferences, but the way is not always documented in the web.... however, the local documentation (call doc) contains the info you may be looking for, see this blog-post
I am not aware of an automatic detection of double spaces or similar but you might end up writing your own little callback-function. Most languages ignore this anyway (perhaps except for Python). Code readability is usually a topic that the programmer(s) should care about... and not the machines ;)
Further tips:
respect the Right-hand text limit, which is the vertical gray line in your editor and shall indicate how many characters a single line of code should have as maximum. If it is a comment, wrap it. If it is an expression, try to outsource some commands to a dedicated variable
use equally long variable names. (There is no style guide as in Python, which says that you should use normal words and underscores etc) E.g. if you have two variables describing a commanded and a measured velocity, you could call them v_cmd and v_act and your code perfectly aligns if you apply the same manipulations to both variables ;)
use section. With %% (the space is important) at the beginning of a line in the editor, you create a section (you'll note the slight yellow background color and the bold writing that follows this command). It is convenient to structure your code. You can even run entire sections Editor-Tab > Run > Run section
Although there are programmers claiming that a good code speaks for itself (and therefore doesn't need any comments), to my experience writing comments has never been a bad idea. It improves the readability of your code
The answer might have been a bit elaborate for such an innocent question ... oO
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
How to write PowerShell script for attached screenshots? I am trying to run and configure installer via PowrShell.
There is no guarantee that this will be possible, as it's possible to (incorrectly) author a Windows Installer package in a way that rejects this. But in many cases, it suffices to find the feature names, property names, and property values involved in the settings you wish to control.
Note that to approach 100% correctness, you will have to consider all properties that get set during the normal UI sequence, or consult documentation provided by the author of the package.
Feature Selection
You can specify which features will be installed by listing their names in the special properties: ADDLOCAL, REMOVE, ADDSOURCE, etc. To find their names, consult documentation, or examine the Feature table of the .msi file.
Note that doing this can evade attempts the author might have made to ensure proper selection of features (for some meaning of proper), and it will also set the property Preselected, which offers the author a way to tweak the behavior in this situation.
Configuration
Windows Installer dialog boxes are all defined in the Dialog table and Control table, but the results can also be augmented by the ControlEvent table and custom actions. In the common case you can look at the Control table to identify the Property name associated with the values you wish to set. For example, an Edit control with Property value TESTPROP will set the property TESTPROP to whatever you type into its associated edit box. Check boxes cross reference the CheckBox table for the value they will set or clear (often simply 1), etc. Radio button groups cross reference the RadioButton table for their values.
Sometimes intermediate values may be set by the controls, and their eventual target properties are then adjusted by a custom action invoked by a Control Event or a sequenced Custom Action.
Alternatives
Instead of poking into the inner bowels of the installation package you are trying to automate, documentation from its author is often much safer. When that's missing, you can find a tool that helps you generate a response transform (much easier to use, but fallible), a tool that helps you explore the tables I described above (harder, but gives as complete an understanding as you can get), or you can create and examine a verbose log file created while installing the package with the settings you desire (middle of the road).
The log file will include all the properties and feature names you need to set on a command line, but probably will include several you do not need to set. Figuring out which is which can still be difficult.
End Result
In the end, you will end up with a command line including some of the following parts. I'm using italics to indicate the parts whose names or values I do not know; those should be substituted with correct values. I've also added parentheticals to explain what each part does; those should be omitted. I've broken the command line across multiple screen lines for clarity.
msiexec /i the.msi /qn (install the.msi silently)
ADDLOCAL="desired,features,here" (select these features)
REMOVE="undesired,features,here" (optional; explicilty unselect these features)
SOMEPROP1="some value1" (specify the value of one or more properties)
SOMEPROP2="some value2"
SOMEPROP3="some value3" (specify more properties as necessary)
Note that property names are almost always going to be upper case and may include underscores. Feature names can be mixed case but will not include spaces. Property values can be anything, and must be quoted if they include spaces or other special characters.
If you plan to use this across multiple systems, note that differences in the target system can affect the correct command lines to use. This is relatively rare; when it happens, it's likely to be due to differing versions of Windows or differing availability of optional dependencies.
The publish function in MATLAB works for both scripts and functions,
while the one for Octave works only for scripts: if I enter
publish myFunc.m
Octave gave
error: publish: Only Octave script files can be published.
Am I able to publish a function in Octave? If yes, how?
You can use Octave Forge generate_html package which is meant to generate html of individual functions. It is mostly used to generate the documentation of Octave Forge packages, and its defaults reflect that, but you could add any style you want.
This package will use the same help text that the help function in Octave sees which is the first block of comments in the file that does not start by Copyright or Author. You can have it in plain text but for nicer formatting, you can use Texinfo. In that case, the first line of the help text should be -*- texinfo -*-. There is a page on the Octave wiki with tips on how to write nice help text including a short section on Texinfo syntax (the actual Texinfo manual can be a bit overwhelming).
In addition to the help text, the generate_html package also identifies %!demo blocks and generates a section with the demo code and output it generates, including figures.
The best way to see how help text and demo blocks work in Octave is to check the source (as #Andy pointed out in the comments). For example, see the source for inpolygon (scroll to the bottom to find the %!demo blocks, right before %!test and %!error). The generate_html package generates this page (note the Demonstration blocks).
This is a "multiple questions in one" question, making lots of assumptions in between, so let's address those first:
1. I'll start by the question in the comment, since that's the easiest: Matlab's publisher is not a code documentation tool. It's a "make a quick report that includes both text and code to show at your supervisor meeting or write a quick point in a blog" tool. So the link you point to is simply irrelevant in this case, since that talks about documentation for matlab code.
2. The fact that matlab's publisher also "works for functions", particularly given the first point here, should be considered to be more of a bug than a feature, or at most as a trivial undocumented extension. If you look at the matlab documentation for the publish command, you'll see it expects a filename, not a function with arguments, and the documentation only talks about scripts and makes no mention of 'function' compatibility.
3. Furthermore, even if you did want to use publisher as a "documentation tool", this is counterintuitive for functions in this format, since you need to provide arguments in order for publisher to work (which will not be shown in the actual report), you'll need a modified version that displays intermediate calculations (as opposed to your normal version which presumably does not), and the function just spews an ugly ans= blabla at the end of the report. If your end goal is documentation, it might be best to write a bespoke script for this anyway, showing proper usage and examples, like matlab does in its actual documentation.
Having said all that, yes, there is a 'cheat' you can do to include a function's code in your published report, which is that, in octave (also matlab since R2016b), functions can be defined locally. A .m file that only contains function definitions is interpreted as a function file, but if there are other non-function-declaration instructions preceding the function definitions (other than comments), then it is seen as a script. So if you publish this script, you effectively get a published report with function code in it:
%% Adding function
% This function takes an input and adds 5 to it.
%% Example inputs
In = 10;
%% The function itself
% Marvel at its beauty!
function Out = myfun(In)
%% Here is where the addition takes place.
% It is a beautiful addition
Out = In + 5;
end
%% Example use
Out = myfun(In)
(If you're not happy about having to create a 'wrapper script' manually, you can always create your own wrapper function that does this automatically).
However, both the matlab and octave publishers are limited tools by design. Like I said earlier, it's more of a "quick report to show numbers and plots to your supervisor" tool, rather than a "make nice documentation or professional reports" tool. Instead, I would invest in a nice automated latex workflow, and have a look at code formatting tools for displaying code, and simply wrap that code in a script that produces output to a file that you can then import into latex. It may sound like more work, but it's a lot more flexible and robust in the long term, particularly since the formatting commands can be very quirky as well as limited.
I need to open a software and give it a value and then execute it to obtain some results
but the problem is that I have many values and each time I put a value manually which is very time consuming. Is there a way to do this automatically with MATLAB?
First of all: your question title and your actual question are quite different. I'm going to give you ideas to answer your question, not your question title.
you need to find out, whether you can run your software in batch mode. That means, you need to be able to control the software from the command-line.
Once you know that, you can use the system command of matlab to run the cmd from your script.
for example:
system( 'mySoftware.exe' -myIndividualParameters )
If it's not possible to pass parameters to your software, it may can read text files, which you can create with matlab before.
Anyway, your question is specifying absolutely nothing. You have to give a lot more information: how is your software obtaining parameters? you can it be started? Which format do the parameters need? Do you want matlab to do something with results of your software?
I have a lot of HTML files (10,000's and GBs worth) scraped from a server and I want to check to make sure the server produces the same results after some modifications but ignore kinds of differences that don't matter, e.g. whitespace, missing newlines, timestamps, small changes in some kinds of number, etc.
Does anyone know of a tool for doing this? I'd really rather not do more filtering than I have to.
(Oh and it needs to run under linux)
You might consider using a clone detector such as our CloneDR. This tool parses large sets of computer program (HTML is special case) files, builds abstract syntax trees representing the essential structure of each files, and compares programs for similarity.
Because it is comparing essential program structure, it ignores inessential differences such as comments and whitespace, and deterimines that two code segments are either identical or one can be obtained from the other by substituting other blocks of code. The latter allows the recognition of code that has been modified in various ways. You can see samples of clone detection runs on a variety of computer languages at the web site.
In your case, what you would be looking for are files in system A which are essentially clones (exact or near misses) of files in system B. As a general rule, if a file a is a variant of file b (e.g., with a few changes) the CloneDr will report it as a clone and show the exact differences.
At the scale of 20,000 files, I can see why you want a tool, and I can see why you want near-miss matches rather than exact matches.
Doesn't run under Linux, but I assume your problem is hard to enough to solve so that isn't what you are optimizing.
I use winmerge alot in windows and from what i can see some people enjoy meld in linux, so perhaps that could do the trick for you
http://meld.sourceforge.net/
Other examples i saw from a quick googling was Kompare,xxdiff.sourceforge.net, and kdiff3.sourceforge.net
(could only post 1 link so wrote the adresses to xxdiff and kdiff3 as text)
Beyond Compare is purchased software that is actually worth the money (I never thought I'd hear myself typing that!). It is GUI based but handles thousands of files very well. It will allow you to specify unimportant changes with regular expressions as well as whitespace (beginning, middle and end of line). The feature set is very extensive, check out a trial download.
I do not work for this company, I just use Beyond Compare every day at work and enjoy it every time!