function out = addSetting(obj,varargin)
% addSetting    Add new setting
%
%  addSetting(PARENTGROUP, NAME) adds a new setting, NAME, to the 
%  specified parent group, PARENTGROUP and returns a Setting oject containing the new setting
%  NAME can be any valid MATLAB variable name. If NAME exists in the specified parent settings group, 
%  MATLAB returns on error.
%
%  addSetting saves the new setting in the the user settings file in the preferences directory. 
%  If the settings file is read-only, the setting is added for the current session, but does not
%  persist across subsequent MATLAB sessions.
%
%  addSetting(PARENTGROUP, NAME, NAME1, VALUE1, ...) specifies settings properties using one or more
%  name-value pair arguments. Specify name-value pairs after all other input arguments.
%
%  Supported properties include:
%
%  Hidden
%   The 'Hidden' indicates whether this setting is a visible setting. When 'Hidden is set to true,
%   the setting is not displayed. The default value for the property is false.
%
%  ReadOnly
%   The 'ReadOnly' property specified the read-only state of the setting. When 'ReadOnly' is set
%   to true, value of the setting cannot be changed.
%
%  PersonalValue
%   The 'PersonalValue' property specifies the personal value of the setting. You must specify a 
%   personal value for a setting when specifying a read-only state of true.
%
%  ValidationFcn
%   The 'ValidationFcn' property specifies the function to validate the setting. Specify the validation
%   function as a function handle. The validation function is used to validate the setting value. MATLAB 
%   invokes the validation function when the value of a setting is about to change. 
%
% Examples:
%
%  Add a 'FontSize' setting to the existing settings group 'mysettings'
%
%      >> s = settings;
%      >> addSetting(s.mysettings, 'FontSize');
%
%  This results in this settings tree 
%
%                             root
%                             /  \    
%                       matlab   mysettings
%                     ......          \
%                                    FontSize 
%
%
%   Add a hidden setting 'FontColor' to the existing settings group 'mysettings', with a validation function 'validateValue'. 
%
%      >> s = settings;
%      >> addSetting(s.mysettings, 'FontColor', 'Hidden', true, 'ValidationFcn', @validateValue);
%
%  This results in this settings tree 
%
%                             root
%                             /  \     
%                       matlab   mysettings
%                     ......     /        \
%                              FontSize  FontColor
%
%  The hidden setting 'FontColor' does not display in the parent settings group:
% 
%      >> s.mysettings
%      ans = 
%       SettingsGroup 'mysettings' with properties:
%          FontSize: [1×1 Setting]
%    
%
%   See also matlab.settings.SettingsGroup, matlab.settings.SettingsGroup/addGroup, matlab.settings.SettingsGroup/removeSetting


%   Copyright 2015-2019 The MathWorks, Inc.

    [results, defaultsUsed] = matlab.settings.internal.parseSettingPropertyValues(varargin);
    % parseSettingPropertyValues function parses and validates user-input for optional property-value pairs with inputParser.
    out = obj.addSettingHelper(results,defaultsUsed);

end
