fix part of sphynx warning in some functions

Author: marcobarilari

docs/source/function_description.rst

@@ -23,12 +23,13 @@ List of functions in the ``src`` folder.
 
 List of functions in the ``src/aperture`` folder.
 
+(to add saveAperture)
+
 .. module:: src.aperture
 
 .. autofunction:: apertureTexture
 .. autofunction:: eccenLogSpeed
 .. autofunction:: getApertureName
-.. autofunction:: saveAperture
 .. autofunction:: saveApertures
 .. autofunction:: smoothOval
 .. autofunction:: smoothRect

src/dot/initDots.m

@@ -20,8 +20,7 @@
     % dots.isSignal : signal dots (1) and those are noise dots (0)
     % dots.directionAllDots
     % dots.lifeTime : in frames
-    % dots.speeds : [ndots, 2] ; horizontal and vertical speed ; in pixels per
-    %   frame
+    % dots.speeds : [ndots, 2] ; horizontal and vertical speed ; in pixels per frame
     % dots.speedPixPerFrame
 
     dots.direction = thisEvent.direction(1);

src/keyboard/checkAbort.m

@@ -1,13 +1,15 @@
 % (C) Copyright 2020 CPP_PTB developers
 
 function checkAbort(cfg, deviceNumber)
-    % checkAbort(cfg, deviceNumber)
     %
-    % Check for experiment abortion from operator
-    % When no deviceNumber is set then it will check the default device
-    % When an abort key s detected this will set a global variable and throw a
+    % Check for experiment abortion from operator. When no deviceNumber is set then it will check
+    % the default device. When an abort key is detected this will set a global variable and throw a
     % specific error that can then be catched.
     %
+    % USAGE:
+    %
+    %   function checkAbort(cfg, deviceNumber)
+    %
     % Maint script
     % try
     %     % Your awesome experiment

src/keyboard/getResponse.m

@@ -1,60 +1,51 @@
 % (C) Copyright 2020 CPP_PTB developers
 
 function responseEvents = getResponse(action, deviceNumber, cfg, getOnlyPress)
-    % responseEvents = getResponse(action, deviceNumber, cfg, getOnlyPress)
     %
-    % Wrapper function to use KbQueue
-    %
-    % The queue will be listening to key presses on a keyboard device:
-    % cfg.keyboard.responseBox or cfg.keyboard.keyboard are 2 main examples.
-    %
-    % When no deviceNumber is set then it will listen to the default device.
-    %
-    % Check the CPP_getResponseDemo for a quick script on how to use it.
-    %
-    %
-    % INPUT
-    %
-    % - action: Defines what we want the function to do
-    %  - init: to initialise the queue
-    %  - start: to start listening to keypresses
-    %  - check: checks all the key presses events since 'start', or since last
-    %    'check' or 'flush' (whichever was the most recent)
-    %    -- can check for demand to abort if the escapeKey is listed in the
-    %       Keys of interest.
-    %    -- can only check for demands to abort when getResponse('check') is called:
-    %       so there will be a delay between the key press and the experiment stopping
-    %    -- abort errors send specific signals that allow the catch to get
-    %       them and allows us to "close" nicely
-    %  - flush: empties the queue of events in case you want to restart from a clean
-    %    queue
-    %  - stop: stops listening to key presses
-    %
-    % - getOnlyPress: if set to true the function will only return the key presses and
-    %    will not return when the keys were released (default=true)
-    %    See the section on OUTPUT below for more info
-    %
-    %
-    %
-    % OUTPUT
-    %
-    % responseEvents: returns all the keypresses and return them as a structure
-    % with field names that make it easier to save the output of in a BIDS
-    % format
-    %
-    % responseEvents.onset : this is an absolute value and you should
-    %   substract the "experiment start time" to get a value relative to when the
-    %   experiment was started.
-    %
-    % responseEvents.trial_type = 'response';
-    %
-    % responseEvents.duration = 0;
-    %
-    % responseEvents.keyName : the name of the key pressed
-    %
-    % responseEvents(iEvent,1).pressed : if
-    %   pressed == 1  --> the key was pressed
-    %   pressed == 0  --> the key was released
+    % Wrapper function to use KbQueue. The queue will be listening to key presses on a keyboard device:
+    % ``cfg.keyboard.responseBox`` or ``cfg.keyboard.keyboard`` are 2 main examples.When no deviceNumber
+    % is set then it will listen to the default device. Check the ``CPP_getResponseDemo`` for a quick
+    % script on how to use it.
+    %
+    % USAGE:
+    %
+    %   responseEvents = getResponse(action, deviceNumber, cfg, getOnlyPress)
+    %
+    % :param action: Defines what we want the function to do
+    % :param deviceNumber: device number of the keyboard or trigger box in MRI
+    % :type deviceNumber: integer
+    % :param cfg:
+    % :param getOnlyPress: if set to true the function will only return the key presses and will not
+    %                      return when the keys were released (default=true). See the section on
+    %                      `Returns` below for more info
+    %
+    % :returns: - :responseEvents: returns all the keypresses and return them as a structure with
+    %                              field names that make it easier to save the output of in a BIDS format
+    %
+    % - ``responseEvents.onset``: this is an absolute value and you should substract the
+    %                              "experiment start time" to get a value relative to when the
+    %                              experiment was started.
+    % - ``responseEvents.trial_type = response``;
+    % - ``responseEvents.duration = 0;``
+    % - ``responseEvents.keyName``: the name of the key pressed
+    % - ``responseEvents(iEvent,1).pressed``: if
+    %  - pressed == 1  --> the key was pressed
+    %  - pressed == 0  --> the key was released
+    %
+    % ``action`` options:
+    %
+    % - ``init``: to initialise the queue
+    % - ``start``: to start listening to keypresses
+    % - ``check``: checks all the key presses events since 'start', or since last 'check' or 'flush'
+    %   (whichever was the most recent)
+    %  - can check for demand to abort if the escapeKey is listed in the Keys of interest
+    %  - can only check for demands to abort when ``getResponse('check')`` is called so there will be
+    %    a delay between the key press and the experiment stopping
+    %  - abort errors send specific signals that allow the catch to get
+    %    them and allows us to "close" nicely
+    % - ``flush``: empties the queue of events in case you want to restart from a clean
+    %   queue
+    % - ``stop``: stops listening to key presses
 
     if nargin < 2 || isempty(deviceNumber)
         deviceNumber = -1;

src/readAndFilterLogfile.m

@@ -1,27 +1,26 @@
 % (C) Copyright 2020 CPP_PTB developers
 
-function outputFiltered = readAndFilterLogfile(columnName, filterBy, varargin)
-    % outputFiltered = readOutputFilter(filterHeader, filterContent, varargin)
+function [outputFiltered] = readAndFilterLogfile(columnName, filterBy, varargin)
     %
     % It will display in the command window the content of the `output.tsv' filtered by one element
-    % of a target column.
+    % of a target column. Dependecies: bids_matlab (from CPP_BIDS)
     %
-    % DEPENDENCIES:
-    %  - bids_matlab (from CPP_BIDS)
+    % USAGE:
     %
-    % INPUT:
+    %   [outputFiltered] = readOutputFilter(filterHeader, filterContent, varargin)
     %
-    %  - columnName: string, the header of the column where the content of insterest is stored
-    %    (e.g., for 'trigger' will be 'trial type')
-    %  - filterBy: string, the content of the column you want to filter out. It can take just
-    %    part of the content name (e.g., you want to display the triggers and you have
-    %    'trigger_motion' and 'trigger_static', 'trigger' as input will do)
-    %  - varargin: either cfg (to display the last run output) or the file path as string
+    % :param columnName: the header of the column where the content of insterest is stored
+    %                    (e.g., for 'trigger' will be 'trial type')
+    % :type columnName: string
+    % :param filterBy: the content of the column you want to filter out. It can take just
+    %                   part of the content name (for example, you want to display the triggers and
+    %                   you have ``trigger_motion`` and ``trigger_static``, ``trigger``' as input
+    %                   will do)
+    % :type filterBy: string
+    % :param varargin: either ``cfg`` (to display the last run output) or the file path as string
     %
-    % OUTPUT:
-    %
-    %  - outputFiltered: dataset with only the specified content, to see it in the command window
-    %    use display(outputFiltered)
+    % :returns: - outputFiltered: dataset with only the specified content, to see it in the command
+    %             window use display(outputFiltered)
 
     % Checke if input is cfg or the file path
     if ischar(varargin{1})

src/utils/degToPix.m

@@ -1,24 +1,21 @@
 % (C) Copyright 2020 CPP_PTB developers
 
 function structure = degToPix(fieldName, structure, cfg)
-    % structure = degToPix(fieldName, structure, cfg)
+    % For a given field value in degrees of visual angle in the structure, this computes its value
+    % in pixel using the pixel per degree value of the cfg structure and returns a structure with
+    % an additional field with Pix suffix holding that new value.
     %
-    % For a given field value in degrees of visual angle in the structure,
-    % this computes its value in pixel using the pixel per degree value of the cfg structure
-    % and returns a structure with an additional field with Pix suffix holding that new value.
+    % USAGE:
     %
+    %   structure = degToPix(fieldName, structure, cfg)
     %
-    % USAGE:
-    % ------
     % fixation.width = 2;
     % cfg.screen.ppd = 10;
     %
     % fixation = degToPix('width', fixation, cfg);
     %
-    % Returns:
-    % -------
+    % - Returns:
     % fixation.widthPix = 20;
-    %
 
     deg = getfield(structure, fieldName); %#ok<GFLD>
 

src/waitForTrigger.m

@@ -1,34 +1,37 @@
 % (C) Copyright 2020 CPP_PTB developers
 
-function lastTriggerTimeStamp = waitForTrigger(varargin)
-    % waitForTrigger(cfg, deviceNumber, quietMode, nbTriggersToWait)
-    %
+function [lastTriggerTimeStamp] = waitForTrigger(varargin)
     % Counts a certain number of triggers coming from the scanner before returning.
     %
+    % USAGE:
+    %
+    %   [lastTriggerTimeStamp] = waitForTrigger([cfg,] [deviceNumber,] [quietMode,] [nbTriggersToWait])
+    %
+    % :param cfg:
+    % :type cfg: struct
+    % :param deviceNumber: device number of the keyboard or trigger box in MRI
+    % :type deviceNumber: integer
+    % :param quietMode: a boolean to make sure nothing is printed on the screen or the prompt
+    % :type quietMode: boolean
+    % :param nbTriggersToWait: number of triggers to wait
+    % :type nbTriggersToWait: integer
+    %
+    % :returns: - :lastTriggerTimeStamp: (optional) it can be used as experimentStart timestamp (``cfg.experimentStart``)
+    %
     % If you are not using the quietMode, it flips and waits for half a TR before starting to
     % check for the next trigger (unless this was the last trigger to wait for and in
     % this case it returns immediately).
     %
     % Will print the count down in the command line and on the PTB window if one is
     % opened.
     %
-    % If the fMRI sequence RT is provided (cgf.MRI.repetitionTime) then it will wait
+    % If the fMRI sequence RT is provided (``cgf.MRI.repetitionTime``) then it will wait
     % for half a RT before starting to check for next trigger, otherwise it will
     % wait 500 ms.
     %
     % When no deviceNumber is set then it will check the default device: this is
     % probably only useful in debug as you will want to make sure you get the
     % triggers coming from the scanner in a real case scenario.
-    %
-    % INPUTS
-    % - varargin{1} = cfg
-    %
-    % - varargin{2} = deviceNumber
-    %
-    % - varargin{3} = quietMode: a boolean to make sure nothing is printed on the screen or
-    % the prompt
-    %
-    % - nvarargin{4} = nbTriggersToWait
 
     [cfg, nbTriggersToWait, deviceNumber, quietMode] = checkInputs(varargin);