Merge branch 'dev/descriptions' into 'development'

fix typos and add comments

See merge request !41

+PlotID/Publish.m

@@ -4,18 +4,26 @@ function Publish(DataPaths,scriptPath, figure, options)
 %   DataPaths contains the path(s) to the research data, for multiple files
 %   use a cell array
 %   scriptPath contains the path to the script, this can be provided with
-%   the simple call of scriptPath = [mfilename('fullpath'),'.m'], note that
-%   the extension is mandatory
+%   the simple call of scriptPath = [mfilename('fullpath'),'.m']
 %
 %   Options:
 %   Location sets the storage location. 'local' sets the storage location
-%   to the current folder (an export folder will be created), 'server' is a
+%   to the current folder (an export folder will be created), 'manual' opens
+%   a explorer window, where you can choose the folder. If you define a export
+%   path in the config file, this will used per default.
 %   remote path, that is defined in the config file.
 %   Two Methods are implemented 'individual' stores the data for
 %   each plot while 'centralized' uses a data folder and uses reference links
 %   to the original data (hdf5 only).
-%   ParentFolder is the folder Name where the exported data is stored if an
+%   'ParentFolder' is the folder Name where the exported data is stored if an
 %   path is used, PlotId will use this path a storagePath
+%   'ConfigFileName' is needed for handling multiple config files (see example)
+%   'CSV' turns a summary table of all exports on or off 
+%
+%   DebugOptions:
+%   'ShowMessage' and 'ForcePublish' are mainly for debugging. 
+%   'ShowMessage' will display Messages for every step of PlotID,
+%   'ForcePublish' will publish even if one step was not successful (not recommended) 
 
 arguments
    DataPaths {mustBeDataPath} % location of the data-file(s)
@@ -23,11 +31,11 @@ arguments
    figure (1,:) {mustBeFigure} % Checks if figure is a figure object
    options.Location {mustBeMember(options.Location ,{'local','server','manual','CI-Test'})} = 'local' % storage path
    options.Method {mustBeMember(options.Method ,{'individual','centralized'})} = 'individual'
-   options.ParentFolder (1,:) {mustBeText} = 'export'
+   options.ParentFolder (1,:) {mustBeText} = 'PlotID_export' % name of the ParentFolder
    options.ConfigFileName (1,:) {mustBeText} = 'config.json' %individual config names possible
    options.CopyUserFCN (1,1) {mustBeNumericOrLogical} = true
-   options.CSV (1,1) {mustBeNumericOrLogical} = false
-   options.ShowMessages(1,1) {mustBeNumericOrLogical} = true
+   options.CSV (1,1) {mustBeNumericOrLogical} = true
+   options.ShowMessages(1,1) {mustBeNumericOrLogical} = false 
    options.ForcePublish (1,1) {mustBeNumericOrLogical} = false %publish anyway
    
 end
@@ -38,7 +46,7 @@ if ~iscell(DataPaths)
       DataPaths = {DataPaths}; %Cell array
 end
 
-% strings will cause problems, we therfore use chars
+% strings will cause problems, therefore chars are used 
 for i=1:numel(DataPaths)
     if isstring(DataPaths{i})
        DataPaths{i} = char(DataPaths{i});
@@ -52,7 +60,7 @@ end
 %catch multiple figures in fig
 if numel(figure) > 1
     figure = figure(1);
-    msg = ['Publish is designed for handeling one figure at once' newline,...
+    msg = ['Publish is designed for handling one figure at once' newline,...
         '- publishes uses only the first figure.' newline , ...
         'Consider an external for loop for multi figure export as provided in example.m'];
     warning(msg);
@@ -68,7 +76,7 @@ end
 ID = figure.Tag;
 
 if isempty(ID)  
-   % no ID found, User dialog for Folder name 
+   % no ID found, user dialog for folder name 
    ID = inputdlg(['No ID defined- ' newline,...
        'Please enter a folder name to continue:'],'Please enter a folder name');
    ID = ID{1};
@@ -80,7 +88,7 @@ end
 %% read config file
 % there is only one config Object (handleClass)
 configObj = PlotID.config(options.ConfigFileName);
-% add user options 
+% read user options from config and set them for Publish
 if isfield(configObj.configData, 'options')
    fldnames = fieldnames(configObj.configData.options);
    for ii=1:numel(fldnames) 
@@ -89,10 +97,9 @@ if isfield(configObj.configData, 'options')
    end
 end
 
-% Error and MSG handeling
+% error and MSG handling object
 dlgObj = PlotID.userDLG(ID,options); 
 
-
 %% storage location
 switch options.Location 
     case 'local'
@@ -103,7 +110,7 @@ switch options.Location
             scriptLocation = fileparts(scriptPath);
             storPath = fullfile(scriptLocation,options.ParentFolder);
         end    
-    case 'exportPath' %legacy
+    case 'exportPath' 
         if isfolder(configObj.exportPath)
            storPath = configObj.exportPath;
         else
@@ -120,7 +127,7 @@ switch options.Location
         storPath = configObj.configData.ServerPath;
     case 'manual' %UI
         storPath = uigetdir();
-    case 'CI-Test'
+    case 'CI-Test' %only for CI tests
         storPath = fullfile(pwd,'CI_files',options.ParentFolder);
 end
 
@@ -129,7 +136,7 @@ folderNameV = char(ID); %visible Folder
 
 %% Create data directory
 overwriteDir = false;
-% if invisible Folder exists, delete it (publish was not succesfull before)
+% if invisible Folder exists, delete it (publish was not successful before)
 if isfolder(fullfile(storPath,folderName))
    rmdir(fullfile(storPath,folderName),'s')
 end
@@ -145,7 +152,7 @@ if isfolder(fullfile(storPath,folderNameV))
        return; %terminate
    end
 end
-% create folder
+% create the folder
 if ~mkdir(fullfile(storPath,folderName))
     dlgObj.error('Directory could not be created - check remote path and permissions');
 end
@@ -162,13 +169,13 @@ dlgObj.userMSG(msg);
 if options.CopyUserFCN 
    fList = fList(~ismember(fList,scriptPath)); % rmv script from list
    fList = fList(~contains(fList,'config.json')); % rmv config.json from list
-   fList = PlotID.removePltIdFiles(fList); % Do not copy files that are part of plot ID
+   fList = PlotID.removePltIdFiles(fList); % Do not copy files that are part of PlotID
    if ~isempty(fList)
        PlotID.createFileCopy(fList,folderName,storPath,ID,'userFcn');
    end
 end
 
-%% Research data handeling
+%% Research data handling
 switch options.Method
     case 'centralized' 
         DataFolderName = 'data';
@@ -259,12 +266,12 @@ catch
    dlgObj.softError('Plot export was not successful');
 end
 
-%% final renaming and error/warning handeling
-% if no error orcurred or if force publish is activated, rename the hidden
+%% final renaming and error/warning handling
+% if no error occurred or if force publish is activated, rename the hidden
 % folder to a non hidden one, otherwise delete it.
 if dlgObj.success || options.ForcePublish
     oldPath = fullfile(storPath,folderName);
-    newPath = strrep(oldPath,'.',''); %remov dot
+    newPath = strrep(oldPath,'.',''); %remove dot
     if overwriteDir
        rmdir(newPath,'s');
        dlgObj.userMSG(['old export ', folderNameV, ' deleted']); 
@@ -272,8 +279,7 @@ if dlgObj.success || options.ForcePublish
     status = movefile(oldPath,newPath); %rename directory
 end
 
-%% CSV EXport
-% ToDo exclude in function
+%% CSV export
 if options.CSV
   T = table();
   T.research_Data = DataPaths'; T.PlotID(:) = {ID};
@@ -286,9 +292,8 @@ if options.CSV
 end
 
 if status 
-    disp(['publishing of ', ID , ' to ', newPath, ' done']); %always displayed onsucess   
-else % publish was not sucessfull! 
-    %replace with error from userDLG Class
+    disp(['publishing of ', ID , ' to ', newPath, ' done']); %always displayed on success   
+else % publish was not successful! 
     dlgObj.error(['publishing of ', ID , ' failed'])
 end
 

+PlotID/TagPlot.m

@@ -2,15 +2,17 @@ function [figs, IDs] = TagPlot(figs, options)
 %TagPlot adds IDs to figures
 %   The ID is placed visual on the figure window and as Tag (property of figure)
 %   TagPlot can tag multiple figures at once.
-%   If a single Plot is taged IDs is a char, otherwise it is a cell array of
+%   If a single Plot is tagged IDs is a char, otherwise it is a cell array of
 %   chars 
 %   options.ProjectID is the project number (string or char), if empty the ID from the
 %   config file is used
 %   
-%   The ID is placed on the 'east' per default, if you want it somwhere
+%   The ID is placed on the 'east' per default, if you want it somewhere
 %   else, use the 'Location' option. 'north','east','south','west' are
 %   predefined, otherwise use the 'custom' option and provide the desired
 %   'Position' (relative to your x- and y-axis limits)
+%   'ConfigFileName' is the config-file which is used for the ProjectID
+%   If you use multiple config files you need to use this option.
 arguments
     figs (1,:) {mustBeFigure}
     options.ProjectID (1,:) {mustBeText}= ''
@@ -76,7 +78,6 @@ for n = 1:numel(figs)
     ylim =get(axes,'YLim');
     xlim =get(axes,'XLim');
     %ID
-    
     position = [options.Position(1), options.Position(2)];
     text(axes,position(1),position(2), IDs{n},'Fontsize',options.Fontsize,...
     'Rotation',Rotation, 'VerticalAlignment','bottom','Color',...

+PlotID/createFileCopy.m

@@ -4,7 +4,7 @@ function [storagePaths, status, msg] = createFileCopy(filePaths,folderName,storP
 % returns the storage paths were files were stored
     
 if ~iscell(filePaths)
-    %fixes Issue if Filepath is a char and not a cell array
+    %fixes Issue if filepath is a char and not a cell array
     filePaths = {filePaths};
 end
         
@@ -72,7 +72,7 @@ try
     msg =([type, ' successfully published']);
 catch
     status = false;
-    warning([type,' export was not sucessful'])
+    warning([type,' export was not successful'])
     if exist('errorMSG')
         error(errorMSG);
     end 

PlotID_example.m

 %% Example Script
-% This Script is ment to demonstrate the capabilities of the PlotID tool.
+% This Script is mend to demonstrate the capabilities of the PlotID tool.
 % please run Initilisation.m before first time use
-%% Clear and set Environment
+
+%% Clear and set environment
 clear; clc; close all;
 addpath('Examples');
 
@@ -14,9 +15,9 @@ addpath('Examples');
 fig1 = figure;
 plot(x,y,'-k'); box off; set(gca, 'TickDir', 'out', 'YLim', [0,4]);
 
-%% Basic Usage
-% PlotID Implementation starts here.
-%% 1. Tag the plot
+% -------------- PlotID Implementation starts here. -------------------------
+
+%% ----- 1. Tag the plot -----
 % TagPlot adds visible ID(s) to the figure(s) and to the figures property 'Tag'
 % every time you run tagPlot you will get an new ID
 
@@ -39,9 +40,9 @@ fig2 = figure; plot(x,y,'-k'); box off; set(gca, 'TickDir', 'out', 'YLim', [0,4]
 
 % You can find the description to all options in the readme
 
-%% 2. Publishing
-% Second part of plotID 
-% Exports your Plot, the research Data and the associated scripts to a
+%%  ----  2. Publishing -----
+% Second part of PlotID 
+% Exports your plot, the research data and the associated scripts to a
 % folder named with your ID
 
 % The functions needs the file location of the script, the location of the
@@ -55,18 +56,19 @@ fig2 = figure; plot(x,y,'-k'); box off; set(gca, 'TickDir', 'out', 'YLim', [0,4]
 scriptPath = [mfilename('fullpath'),'.m']; 
 
 % file paths of the datasets used for the plot (don't forget the extension) 
+% note: use absolute paths for best practice
 % datapath = 'test_data.mat'; 
 locations =  datapath; 
 
 %call publish
 PlotID.Publish(locations,scriptPath, fig2)
 
-% your plot, script and all the data that your provide are now published
-
+% Your plot, script and all the data that your provide are now published.
 
+% ---------------------------------
 %% Further examples and help
 % You find more examples in the Examples folder:
-% Advanced usage 
-% Working with HDF5-files
-% Using a central data folder
-% How to use advanced config-files
+%   - Advanced usage 
+%   - Working with HDF5-files
+%   - Using a central data folder
+%   - How to use advanced config-files
\ No newline at end of file