ardour/livetrax
13
0
Fork 0
Code

Fix invalid use of Doxygen "@param" command

Browse Source 
This is never for inline references to parameters, only for starting parameter
documentation blocks.  The "@p" command is for this, although unfortunately
Doxygen doesn't actually do anything with it and it's just an alias for code
text.
This commit is contained in:
David Robillard 2022-10-30 20:44:28 -04:00
parent 96bab3ce46
commit bdacfb8724
31 changed files with 68 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
gtk2_ardour/editor.cc
View File

@ -2701,13 +2701,16 @@ Editor::get_state () const
return *node;
}
/** if @param trackview_relative_offset is true, @param y y is an offset into the trackview area, in pixel units
* if @param trackview_relative_offset is false, @param y y is a global canvas * coordinate, in pixel units
/** Find a TimeAxisView by y position.
*
* @return pair: TimeAxisView that y is over, layer index.
* TimeAxisView may be 0. Layer index is the layer number if the TimeAxisView
* is valid and is in stacked or expanded region display mode, otherwise 0.
*
* TimeAxisView may be 0. Layer index is the layer number if the TimeAxisView is valid and is
* in stacked or expanded region display mode, otherwise 0.
* If @p trackview_relative_offset is true, then @p y is an offset into the
* trackview area. Otherwise, @p y is a global canvas coordinate. In both
* cases, @p y is in pixels.
*
* @return The TimeAxisView that @p y is over, and the layer index.
*/
std::pair<TimeAxisView *, double>
Editor::trackview_by_y_position (double y, bool trackview_relative_offset) const

6
gtk2_ardour/editor_ops.cc
View File

@ -2159,7 +2159,7 @@ Editor::temporal_zoom_to_sample (bool coarser, samplepos_t sample)
return;
}
/* zoom focus is automatically taken as @param sample when this
/* zoom focus is automatically taken as @p sample when this
method is used.
*/
@ -9629,8 +9629,8 @@ Editor::effective_ripple_mark_start (boost::shared_ptr<Playlist> target_playlist
{
#if 0 /* I do not agree with this behavior - at the very least it ignores regions on *other* tracks and the markers that might be associated with them -Ben */
/* in the target playlist, find the region before the target
* (implicitly given by @param at. Allow all markers that occur between
* the end of the region and @param at to move too. This is
* (implicitly given by @p pos. Allow all markers that occur between
* the end of the region and @p pos to move too. This is
* desired/expected by many (most?) ripple-edit using folk.
*/

2
gtk2_ardour/processor_box.cc
View File

@ -3934,7 +3934,7 @@ ProcessorBox::get_editor_window (boost::shared_ptr<Processor> processor, bool us
/* This method may or may not return a Window, but if it does not it
* will modify the parent mixer strip appearance layout to allow
* "editing" the @param processor that was passed in.
* "editing" the @p processor that was passed in.
*
* So for example, if the processor is an Amp (gain), the parent strip
* will be forced back into a model where the fader controls the main gain.

2
gtk2_ardour/public_editor.h
View File

@ -178,7 +178,7 @@ public:
/** Set the mouse mode (gain, object, range, timefx etc.)
* @param m Mouse mode (defined in editing_syms.h)
* @param force Perform the effects of the change even if no change is required
* (ie even if the current mouse mode is equal to @param m)
* (ie even if the current mouse mode is equal to @p m)
*/
virtual void set_mouse_mode (Editing::MouseMode m, bool force = false) = 0;

4
gtk2_ardour/time_axis_view.cc
View File

@ -1240,8 +1240,8 @@ TimeAxisView::parameter_changed (string const & what_changed)
}
/** @return Pair: TimeAxisView, layer index.
* TimeAxisView is non-0 if this object covers @param y, or one of its children
* does. @param y is an offset from the top of the trackview area.
* TimeAxisView is non-0 if this object covers @p y, or one of its children
* does. @p y is an offset from the top of the trackview area.
*
* If the covering object is a child axis, then the child is returned.
* TimeAxisView is 0 otherwise.

2
libs/ardour/ardour/ardour.h
View File

@ -88,7 +88,7 @@ namespace ARDOUR {
LIBARDOUR_API void set_global_ui_scale_factor (float s);
/* the @param ui_handler will be called if there are old configuration
/* the @p ui_handler will be called if there are old configuration
* files to be copied. It should (probably) ask the user about the
* action, and return true or false depending on whether or not the
* copy should take place.

4
libs/ardour/ardour/filesystem_paths.h
View File

@ -30,8 +30,8 @@ namespace ARDOUR {
/**
* @return the path to the directory used to store user specific
* configuration files for the given @param version of the program.
* If @param version is negative, the build-time string PROGRAM_VERSION
* configuration files for the given @p version of the program.
* If @p version is negative, the build-time string PROGRAM_VERSION
* will be used to determine the version number.
*
* @post user_config_directory() exists IF version was negative.

8
libs/ardour/ardour/port_engine.h
View File

@ -132,7 +132,7 @@ public:
/** Query port name
*
* @param port \ref PortHandle
* @return the name of the port referred to by @param port . If the port
* @return the name of the port referred to by @p port . If the port
* does not exist, return an empty string.
*/
virtual std::string get_port_name (PortHandle port) const = 0;
@ -432,7 +432,7 @@ public:
virtual void set_latency_range (PortHandle port, bool for_playback, LatencyRange r) = 0;
/** Return the latency range for the port referred to by \p port .
* The playback range will be returned if @param for_playback is true,
* The playback range will be returned if @p for_playback is true,
* otherwise the capture range will be returned.
*
* @param port The PortHandle to query
@ -460,8 +460,8 @@ public:
*/
virtual void get_physical_outputs (DataType type, std::vector<std::string>& names) = 0;
/** Store into @param names the names of all ports with the IsInput and
* IsPhysical flags set, that handle data of type @param type .
/** Store into @p names the names of all ports with the IsInput and
* IsPhysical flags set, that handle data of type @p type .
*
* This can be used to discover inputs associated with hardware devices.
*/

4
libs/ardour/ardour/stripable.h
View File

@ -138,7 +138,7 @@ class LIBARDOUR_API Stripable : public SessionObject,
/* "well-known" controls for an EQ in this route. Any or all may
* be null. eq_band_cnt() must return 0 if there is no EQ present.
* Passing an @param band value >= eq_band_cnt() will guarantee the
* Passing an @p band value >= eq_band_cnt() will guarantee the
* return of a null ptr (or an empty string for eq_band_name()).
*/
virtual uint32_t eq_band_cnt () const = 0;
@ -189,7 +189,7 @@ class LIBARDOUR_API Stripable : public SessionObject,
virtual boost::shared_ptr<AutomationControl> send_pan_azimuth_controllable (uint32_t n) const = 0;
virtual boost::shared_ptr<AutomationControl> send_pan_azimuth_enable_controllable (uint32_t n) const = 0;
/* for the same value of @param n, this returns the name of the send
/* for the same value of @p n, this returns the name of the send
* associated with the pair of controllables returned by the above two methods.
*/
virtual std::string send_name (uint32_t n) const = 0;

2
libs/ardour/ardour/transport_fsm.h
View File

@ -26,7 +26,7 @@ struct TransportFSM
/* All code related to this object is expected to be run synchronously
* and single-threaded from the process callback. It can be re-entrant
* if handling one transport state change queues another state change,
* but that is handled explicitly (see the @param processing member and
* but that is handled explicitly (see the @p processing member and
* its usage).
*/

2
libs/ardour/automation_list.cc
View File

@ -117,7 +117,7 @@ AutomationList::AutomationList (const AutomationList& other, timepos_t const & s
}
/** @param id is used for legacy sessions where the type is not present
* in or below the AutomationList node. It is used if @param id is non-null.
* in or below the AutomationList node. It is used if @p id is non-null.
*/
AutomationList::AutomationList (const XMLNode& node, Evoral::Parameter id)
: ControlList(id, ARDOUR::ParameterDescriptor(id), Temporal::AudioTime) /* domain may change in ::set_state */

2
libs/ardour/disk_reader.cc
View File

@ -721,7 +721,7 @@ DiskReader::overwrite_existing_audio ()
Sample* buf = (*chan)->rbuf->buffer ();
ReaderChannelInfo* rci = dynamic_cast<ReaderChannelInfo*> (*chan);
/* Note that @param start is passed by reference and will be
/* Note that @p start is passed by reference and will be
* updated by the ::audio_read() call
*/

2
libs/ardour/midi_buffer.cc
View File

@ -158,7 +158,7 @@ MidiBuffer::push_back(const Evoral::Event<TimeType>& ev)
/** Push MIDI data into the buffer.
*
* Note that the raw MIDI pointed to by @param data will be COPIED and unmodified.
* Note that the raw MIDI pointed to by @p data will be COPIED and unmodified.
* That is, the caller still owns it, if it needs freeing it's Not My Problem(TM).
* Realtime safe.
* @return false if operation failed (not enough room)

2
libs/ardour/playlist.cc
View File

@ -2764,7 +2764,7 @@ Playlist::uses_source (boost::shared_ptr<const Source> src, bool shallow) const
* incredibly deep and time-consuming recursion, and at worst
* cycles if the user has managed to create cycles of reference
* between compound regions. We generally only this during
* cleanup, and @param shallow is passed as true.
* cleanup, and @p shallow is passed as true.
*/
if (r->uses_source (src, shallow)) {
return true;

2
libs/ardour/region.cc
View File

@ -379,7 +379,7 @@ Region::Region (boost::shared_ptr<const Region> other, timecnt_t const & offset)
assert (_type == other->data_type());
}
/** Create a copy of @param other but with different sources. Used by filters */
/** Create a copy of @p other but with different sources. Used by filters */
Region::Region (boost::shared_ptr<const Region> other, const SourceList& srcs)
: SessionObject (other->session(), other->name())
, _type (srcs.front()->type())

4
libs/ardour/session.cc
View File

@ -2689,7 +2689,7 @@ Session::ensure_route_presentation_info_gap (PresentationInfo::order_t first_new
return;
}
/* create a gap in the presentation info to accommodate @param how_many
/* create a gap in the presentation info to accommodate @p how_many
* new objects.
*/
StripableList sl;
@ -4834,7 +4834,7 @@ Session::new_audio_source_path_for_embedded (const std::string& path)
return newpath;
}
/** Return true if there are no audio file sources that use @param name as
/** Return true if there are no audio file sources that use @p name as
* the filename component of their path.
*
* Return false otherwise.

2
libs/ardour/slavable_automation_control.cc
View File

@ -194,7 +194,7 @@ SlavableAutomationControl::add_master (boost::shared_ptr<AutomationControl> m)
if (res.second) {
/* note that we bind @param m as a weak_ptr<AutomationControl>, thus
/* note that we bind @p m as a weak_ptr<AutomationControl>, thus
avoiding holding a reference to the control in the binding
itself.
*/

4
libs/ardour/smf_source.cc
View File

@ -487,7 +487,7 @@ SMFSource::append_event_samples (const WriterLock& lock,
return;
}
/* a distance measure that starts at @param position (audio time) and
/* a distance measure that starts at @p position (audio time) and
extends for ev.time() (audio time)
*/
const timecnt_t distance (timepos_t (ev.time()), timepos_t (position));
@ -511,7 +511,7 @@ SMFSource::append_event_samples (const WriterLock& lock,
assert (!_length || (_length.time_domain() == Temporal::BeatTime));
_length = timepos_t (max (_length.beats(), ev_time_beats));
/* a distance measure that starts at @param _last_ev_time_samples (audio time) and
/* a distance measure that starts at @p _last_ev_time_samples (audio time) and
extends for ev.time() (audio time)
*/
const timecnt_t delta_distance (timepos_t (ev.time()), timepos_t (_last_ev_time_samples));

2
libs/ardour/source.cc
View File

@ -550,7 +550,7 @@ bool
Source::get_segment_descriptor (TimelineRange const & range, SegmentDescriptor& segment)
{
/* Note: since we disallow overlapping segments, any overlap between
the @param range and an existing segment counts as a match.
the @p range and an existing segment counts as a match.
*/
for (auto const & sd : segment_descriptors) {

4
libs/ardour/triggerbox.cc
View File

@ -952,7 +952,7 @@ Trigger::compute_quantized_transition (samplepos_t start_sample, Temporal::Beats
{
/* XXX need to use global grid here is quantization == zero */
/* Given the value of @param start, determine, based on the
/* Given the value of @p start, determine, based on the
* quantization, the next time for a transition.
*/
@ -1228,7 +1228,7 @@ Trigger::start_and_roll_to (samplepos_t start_pos, samplepos_t end_position, Tri
/* We could have reached the end. Check and restart, because
* TriggerBox::fast_forward() already determined that we are
* the active trigger at @param end_position
* the active trigger at @p end_position
*/
if (_state == Stopped) {

8
libs/canvas/canvas.cc
View File

@ -572,8 +572,8 @@ GtkCanvas::pick_current_item (int state)
pick_current_item (Duple (x, y), state);
}
/** Given @param point (a position in window coordinates)
* and mouse state @param state, check to see if _current_item
/** Given @p point (a position in window coordinates)
* and mouse state @p state, check to see if _current_item
* (which will be used to deliver events) should change.
*/
void
@ -656,7 +656,7 @@ GtkCanvas::pick_current_item (Duple const & point, int state)
}
/** Deliver a series of enter & leave events based on the pointer position being at window
* coordinate @param point, and pointer @param state (modifier keys, etc)
* coordinate @p point, and pointer @p state (modifier keys, etc)
*/
void
GtkCanvas::deliver_enter_leave (Duple const & point, int state)
@ -679,7 +679,7 @@ GtkCanvas::deliver_enter_leave (Duple const & point, int state)
enter_event.state = state;
/* Events delivered to canvas items are expected to be in canvas
* coordinates but @param point is in window coordinates.
* coordinates but @p point is in window coordinates.
*/
Duple c = window_to_canvas (point);

4
libs/canvas/canvas/rectangle.h
View File

@ -73,8 +73,8 @@ public:
void set_x1 (Coord);
void set_y1 (Coord);
/** return @param y as a floating point fraction of the overall
* height of the rectangle. @param y is in canvas coordinate space.
/** return @p y as a floating point fraction of the overall
* height of the rectangle. @p y is in canvas coordinate space.
*
* A value of zero indicates that y is at the bottom of the
* rectangle; a value of 1 indicates that y is at the top.

2
libs/evoral/ControlList.cc
View File

@ -1774,7 +1774,7 @@ ControlList::rt_safe_earliest_event_linear_unlocked (Temporal::timepos_t const &
/* delta between the two spanning points is <= 1,
consider the next point as the answer, but only if the next
point is actually beyond @param start.
point is actually beyond @p start.
*/
if (next->when > start) {

2
libs/fluidsynth/src/fluid_chan.c
View File

@ -114,7 +114,7 @@ fluid_channel_init(fluid_channel_t *chan)
}
/*
@param is_all_ctrl_off if nonzero, only resets some controllers, according to
@p is_all_ctrl_off if nonzero, only resets some controllers, according to
https://www.midi.org/techspecs/rp15.php
*/
void

2
libs/pbd/pbd/event_loop.h
View File

@ -127,7 +127,7 @@ private:
/* @param factory : a function that can be called (with an
* argument specifying the @param number_of_requests) to create and
* return a request buffer for communicating with @param name)
* return a request buffer for communicating with @p name)
*/
void* (*factory)(uint32_t nunber_of_requests);
};

2
libs/surfaces/mackie/strip.cc
View File

@ -1055,7 +1055,7 @@ Strip::display (uint32_t lcd_number, uint32_t line_number, const std::string& li
retval << ' '; // add the left pad space
}
// ascii data to display. @param line is UTF-8
// ascii data to display. `line` is UTF-8
string ascii = Glib::convert_with_fallback (line, "UTF-8", "ISO-8859-1", "_");
string::size_type len = ascii.length();
if (len > max_char_count) {

6
libs/surfaces/mackie/surface.cc
View File

@ -608,7 +608,7 @@ Surface::master_display (uint32_t line_number, const std::string& line)
// offset (0 to 0x37 first line, 0x38 to 0x6f for second line)
retval << (49 + (line_number * 0x38)); // 9th position
// ascii data to display. @param line is UTF-8
// ascii data to display. `line` is UTF-8
string ascii = Glib::convert_with_fallback (line, "UTF-8", "ISO-8859-1", "_");
string::size_type len = ascii.length();
if (len > 6) {
@ -1564,7 +1564,7 @@ Surface::display_line (string const& msg, int line_num)
} else {
/* ascii data to display. @param msg is UTF-8 which is not legal. */
/* ascii data to display. @p msg is UTF-8 which is not legal. */
string ascii = Glib::convert_with_fallback (msg, "UTF-8", "ISO-8859-1", "_");
string::size_type len = ascii.length();
@ -1584,7 +1584,7 @@ Surface::display_line (string const& msg, int line_num)
return midi_msg;
}
/** display @param msg on the 55x2 screen for @param msecs milliseconds
/** display @p msg on the 55x2 screen for @p msecs milliseconds
*
* @param msg is assumed to be UTF-8 encoded, and will be converted
* to ASCII with an underscore as fallback character before being

14
libs/temporal/tempo.cc
View File

@ -1782,8 +1782,8 @@ TempoMap::_get_tempo_and_meter (typename const_traits_t::tempo_point_type & tp,
* and meter passed in.
*
* Then advance through all points, resetting either tempo and/or meter
* until we find a point beyond (or equal to, if @param can_match is
* true) the @param arg (end time)
* until we find a point beyond (or equal to, if @p can_match is
* true) the @p arg (end time)
*/
for (tp = tstart, mp = mstart, p = begini; p != endi; ++p) {
@ -1837,7 +1837,7 @@ TempoMap::_get_tempo_and_meter (typename const_traits_t::tempo_point_type & tp,
void
TempoMap::get_grid (TempoMapPoints& ret, superclock_t start, superclock_t end, uint32_t bar_mod) const
{
/* note: @param bar_mod is "bar modulo", and describes the N in "give
/* note: @p bar_mod is "bar modulo", and describes the N in "give
me every Nth bar". If the caller wants every 4th bar, bar_mod ==
4. If we want every point defined by the tempo note type (e.g. every
quarter not, then bar_mod is zero.
@ -1861,7 +1861,7 @@ TempoMap::get_grid (TempoMapPoints& ret, superclock_t start, superclock_t end, u
/* first task: get to the right starting point for the requested
* grid. if bar_mod is zero, then we'll start on the next beat after
* @param start. if bar_mod is non-zero, we'll start on the first bar
* after @param start. This bar position may or may not be a part of the
* after @p start. This bar position may or may not be a part of the
* grid, depending on whether or not it is a multiple of bar_mod.
*
* final argument = true means "return the iterator corresponding the
@ -2568,12 +2568,12 @@ TempoMap::can_remove (MeterPoint const & m) const
return !is_initial (m);
}
/** returns the duration (using the domain of @param pos) of the supplied BBT time at a specified sample position in the tempo map.
/** returns the duration (using the domain of @p pos) of the supplied BBT time at a specified sample position in the tempo map.
* @param pos the frame position in the tempo map.
* @param bbt the distance in BBT time from pos to calculate.
* @param dir the rounding direction..
* @return the timecnt_t that @param bbt represents when starting at @param pos, in
* the time domain of @param pos
* @return the timecnt_t that @p bbt represents when starting at @p pos, in
* the time domain of @p pos
*/
timecnt_t
TempoMap::bbt_duration_at (timepos_t const & pos, BBT_Offset const & dur) const

8
libs/temporal/temporal/tempo.h
View File

@ -959,10 +959,10 @@ class /*LIBTEMPORAL_API*/ TempoMap : public PBD::StatefulDestructible
* It also returns an iterator which may point at the latter of the two
* points (tempo & meter; always the meter point if they are at the
* same time) OR may point at the iterator *after* the latter of the
* two, depending on whether or not @param ret_iterator_after_not_at is
* two, depending on whether or not @p ret_iterator_after_not_at is
* true or false.
*
* If @param can_match is true, the points used can be located at the
* If @p can_match is true, the points used can be located at the
* given time. If false, they must be before it. Setting it to false is
* useful when you need to know the TempoMetric in effect at a given
* time if there was no tempo or meter point at that time.
@ -1000,7 +1000,7 @@ class /*LIBTEMPORAL_API*/ TempoMap : public PBD::StatefulDestructible
Points::iterator get_tempo_and_meter (TempoPoint *& t, MeterPoint *& m, superclock_t sc, bool can_match, bool ret_iterator_after_not_at) {
/* because @param this is non-const (because the method is not
/* because `this` is non-const (because the method is not
* marked const), the following:
_points.begin()
@ -1020,7 +1020,7 @@ class /*LIBTEMPORAL_API*/ TempoMap : public PBD::StatefulDestructible
Points::const_iterator get_tempo_and_meter (TempoPoint const *& t, MeterPoint const *& m, BBT_Time const & bbt, bool can_match, bool ret_iterator_after_not_at) const {
/* because @param this is const (because the method is marked
/* because `this` is const (because the method is marked
* const), the following:
_points.begin()

10
libs/temporal/temporal/timeline.h
View File

@ -142,22 +142,22 @@ class LIBTEMPORAL_API timepos_t : public int62_t {
* explicit methods with clear semantics.
*/
/** Compute the distance between this timepos_t and @param p
/** Compute the distance between this timepos_t and @p p
* such that: this + distance = p
*
* This means that if @param p is later than this, distance is positive;
* if @param p is earlier than this, distance is negative.
* This means that if @p p is later than this, distance is positive;
* if @p p is earlier than this, distance is negative.
*
* Note that the return value is a timecnt_t whose position member
* is equal to the value of this. That means if the distance uses
* musical time value, the distance may not have constant value
* at other positions on the timeline.
*
* @return this - @param p
* @return this - @p p
*/
timecnt_t distance (timepos_t const & p) const;
/* computes a new position value that is @param d earlier than this */
/* computes a new position value that is @p d earlier than this */
timepos_t earlier (timepos_t const & d) const; /* treat d as distance measured from timeline origin */
timepos_t earlier (timecnt_t const & d) const;

2
libs/temporal/timeline.cc
View File

@ -619,7 +619,7 @@ timepos_t::expensive_add (timepos_t const & other) const
/* */
/* ::distance() assumes that @param other is later on the timeline than this, and
/* ::distance() assumes that @p other is later on the timeline than this, and
* thus returns a positive value if this condition is satisfied.
*/