[Lilypond-auto] Issue 4117 in lilypond: Check and correct relation between markup and music function arguments and documentation

[lilypond]

Status: Accepted
Owner: ----
Labels: Type-Documentation

New issue 4117 by address@hidden: Check and correct relation between markup  
and music function arguments and documentation
https://code.google.com/p/lilypond/issues/detail?id=4117

In Guilev2, procedure-source is no longer available for getting the  
original argument list of a function.  That is a problem when generating  
the IR, so I thought that maybe one does not need the original argument  
list names: the _number_ is known, and the documentation guidelines say one  
should document them left from right.  So just looking at the unique  
mentions of @var should be enough.  With music functions, the order might  
make sense done differently (the following list does not do this however),  
documenting optional arguments after mandatory ones.

It turns out that compliance with that documentation rule is abysmal, so  
one will lean towards just recording the argument names at definition time  
explicitly in order to get reasonable robust results and retain the  
flexibility to document in a different order where it really makes sense.   
At the same time, it might make sense to review the correspondence between  
argument list names and documentation.  Particularly the cases where  
arguments go undocumented, or @var occurences that are not actually  
arguments but either a misspelling or some non-variable/parameter and thus  
a misuse of @var (cf \footnote below).

So I compiled a list of mismatches.  Left are the actual arguments, right  
the occurences of @var with duplicates removed.

If someone wants to tackle this and finds that the idea of explaining  
optional arguments last is definitely the best and finds that this list  
suffers from far too many false positives (or missing negatives) due to it  
being compiled without that rule in mind, I can revise the code used for  
compiling this list.

But as a first measure, it would be good to look for those cases where  
there are serious mismatches between left and right beyond just the order  
of arguments.

warning: music function `allowVoltaHook' not documented.
bold-markup: (arg)/()
caps-markup: (arg)/()
dynamic-markup: (arg)/()
fontCaps-markup: (arg)/()
fontsize-markup: (increment arg)/(increment)
huge-markup: (arg)/()
large-markup: (arg)/()
larger-markup: (arg)/()
magnify-markup: (sz arg)/()
medium-markup: (arg)/()
normal-text-markup: (arg)/()
normalsize-markup: (arg)/()
number-markup: (arg)/()
replace-markup: (replacements arg)/(arg replacements)
roman-markup: (arg)/()
sans-markup: (arg)/()
simple-markup: (str)/()
small-markup: (arg)/()
smaller-markup: (arg)/()
teeny-markup: (arg)/()
text-markup: (arg)/()
tiny-markup: (arg)/()
upright-markup: (arg)/()
center-align-markup: (arg)/()
center-column-markup: (args)/()
combine-markup: (arg1 arg2)/()
fill-line-markup: (args)/(markups line-width)
fill-with-pattern-markup: (space dir pattern left right)/(left right  
pattern space dir)
general-align-markup: (axis dir arg)/(arg axis dir)
halign-markup: (dir arg)/(dir)
hcenter-in-markup: (length arg)/(arg length)
justify-line-markup: (args)/(markups line-width)
justify-markup: (args)/(X)
justify-string-markup: (arg)/()
left-column-markup: (args)/()
lower-markup: (amount arg)/(arg amount)
pad-markup-markup: (amount arg)/()
pad-to-box-markup: (x-ext y-ext arg)/(arg x-ext y-ext)
put-adjacent-markup: (axis dir arg1 arg2)/(arg2 arg1)
raise-markup: (amount arg)/(arg amount)
right-column-markup: (args)/()
rotate-markup: (ang arg)/(ang)
translate-markup: (offset arg)/(arg offset)
translate-scaled-markup: (offset arg)/(arg offset)
vcenter-markup: (arg)/()
wordwrap-markup: (args)/(X)
wordwrap-string-markup: (arg)/()
arrow-head-markup: (axis dir filled)/(filled)
beam-markup: (width slope thickness)/()
draw-circle-markup: (radius thickness filled)/(radius thickness)
draw-line-markup: (dest)/()
epsfile-markup: (axis size file-name)/(axis size)
filled-box-markup: (xext yext blot)/(xext yext)
scale-markup: (factor-pair arg)/(arg factor-pair)
triangle-markup: (filled)/()
customTabClef-markup: (num-strings staff-space)/()
note-by-number-markup: (log dot-count dir)/(dir)
note-markup: (duration dir)/(dir duration)
rest-by-number-markup: (log dot-count)/()
score-markup: (score)/()
tied-lyric-markup: (str)/()
woodwind-diagram-markup: (instrument user-draw-commands)/()
auto-footnote-markup: (mkup note)/(note mkup)
backslashed-digit-markup: (num)/()
char-markup: (num)/()
footnote-markup: (mkup note)/(note mkup)
fraction-markup: (arg1 arg2)/()
lookup-markup: (glyph-name)/()
override-markup: (new-prop arg)/(new-prop)
pattern-markup: (count axis space pattern)/(count pattern space axis)
property-recursive-markup: (symbol)/()
slashed-digit-markup: (num)/()
stencil-markup: (stil)/()
with-color-markup: (color arg)/(arg color)
with-dimensions-markup: (x y arg)/(arg x y)
justified-lines-markup-list: (args)/(X)
override-lines-markup-list: (new-prop args)/()
wordwrap-internal-markup-list: (justify args)/()
wordwrap-lines-markup-list: (args)/(X)
wordwrap-string-internal-markup-list: (justify arg)/()
acciaccatura: (music)/()
addChordShape: (key-symbol tuning shape-definition)/(shape-definition  
chord-shape-table key-symbol tuning)
addInstrumentDefinition: (name lst)/(name list)
addQuote: (name music)/(music name)
afterGrace: (main grace)/(grace main)
allowVoltaHook: (bar)/()
alterBroken: (property arg item)/(property item arg)
appendToTag: (tag more music)/(more music tag)
applyOutput: (ctx proc)/()
assertBeamSlope: (comp)/()
autochange: (music)/()
balloonGrobText: (grob-name offset text)/(text grob-name offset)
balloonText: (offset text)/(text offset)
chordRepeats: (event-types music)/(music event-types)
compoundMeter: (args)/()
crossStaff: (notes)/()
cueDuring: (what dir main-music)/(what main-music dir)
cueDuringWithClef: (what dir clef main-music)/(what main-music dir)
displayLilyMusic: (port music)/(music port)
displayMusic: (port music)/(music port)
displayScheme: (port expr)/(expr port)
endSpanners: (music)/()
eventChords: (music)/()
featherDurations: (factor argument)/(argument factor)
footnote: (mark offset footnote item)/(footnote item mark offset \default  
\tweak)
harmonicByFret: (fret music)/(music fret)
harmonicByRatio: (ratio music)/(music ratio)
inversion: (around to music)/(music around to)
keepWithTag: (tags music)/(music tags)
languageSaveAndChange: (language)/()
magnifyMusic: (mag music)/(music mag)
mark: (label)/()
modalInversion: (around to scale music)/(music around scale to)
modalTranspose: (from to scale music)/(music from to scale)
octaveCheck: (pitch)/()
offset: (property offsets item)/(property item offsets)
ottava: (octave)/()
partcombineForce: (type once)/()
partial: (dur)/()
pointAndClickTypes: (types)/()
pushToTag: (tag more music)/(more music tag)
relative: (pitch music)/(music pitch)
removeWithTag: (tags music)/(music tags)
resetRelativeOctave: (pitch)/()
scaleDurations: (fraction music)/(music fraction)
settingsFrom: (ctx music)/(music ctx)
shape: (offsets item)/(item offsets)
shiftDurations: (dur dots arg)/(arg dur dots)
slashedGrace: (music)/()
spacingTweaks: (parameters)/()
storePredefinedDiagram: (fretboard-table chord tuning  
diagram-definition)/(diagram-definition chord tuning)
styledNoteHeads: (style heads music)/(heads music style)
tabChordRepeats: (event-types music)/(music event-types)
tag: (tags music)/(music tags)
time: (beat-structure fraction)/(fraction beat-structure)
times: (fraction music)/(music fraction)
tocItem: (text)/()
transpose: (from to music)/(music from to)
transposedCueDuring: (what dir pitch main-music)/(what pitch main-music dir)
transposition: (pitch)/()
tuplet: (ratio tuplet-span music)/(music ratio tuplet-span)
tweak: (prop value item)/(item prop value)
void: (arg)/()

--
You received this message because this project is configured to send all  
issue notifications to this address.
You may adjust your notification preferences at:
https://code.google.com/hosting/settings