Library reference ordering and inherited method doclet writeout

[kevinstadler]

I'm currently reorganizing the processing-sound library reference/javadoc and ran into two issues/questions that people more knowledgable than me will hopefully be able to help me with...

1. the relevant code for this one is probably to be found over in the processing-website repo, but I'll ask it here anyway: the default order of the categories (and subcategories) within the reference listing is alphabetic, but ideally I would like a slightly different ordering for the sound library reference. I can see that the core processing reference also uses a custom ordering of categories, but I can't quite see where the order is actually specified in the current codebase? It seems to be somehow controlled by the Shortcuts component, but I can't seem to find where this is actually instantiated. Some ordering code was introduced by @runemadsen with processing/processing4@a8f9031 but taken out again by processing/processing4@48b326b, yet the custom ordering on the website is still in place...

2. @fdoflorenzano probably knows more about this: @webref annotated methods that are inherited from superclasses are currently not rendered/written to json for the subclasses. Is there a way to turn on doclet generation of inherited methods, either on a per-case basis, or simply for the entire run of the processing-sound doclet build? I tried using {@inheritDoc} but it doesn't look like the doclet supports automatic expansion for this...

Many thanks! Kevin

[runemadsen]

Thanks for the ping @kevinstadler. This sent me down a bit of a rabbit hole, since I simply don't remember the current state of the sorting for the main processing reference. This is what I know: We have a useTree function that can sort the categories as they come in. We have an order object defined which dictates can be used in the useTree hook. But it's currently commented out, and the reference is not sorted according to that sort order on the website. This makes me think that we currently just showing the reference categories in the way it shows up in the exported JSON, which means that they are not sorted at all. This would be very easy to change, though. As far as making a sort order work for the sound library, I'm more than happy to hard code a custom sort order for you in the processing-website repo code, or we could find a way to make it easier for library maintainers to define this sort order – either in a JSON file we carry over via this script or something else. What do you think?

[kevinstadler]

Thanks for the swift response! Regarding the sound library ordering I'm easy in terms of whatever works.. Being able to specify a category/subcategory order object in a .json file with the other reference files would definitely transfer better to other libraries, but if that's out of scope then a hard-coded one for the sound library will certainly do.

Just following up on myself re: the second issue: I realised that generating json files for all inherited methods would open quite a can of worms, so I've been playing with selectively generating/duplicating json files instead. Below is a small shell script that I hacked together which makes copies of the superclass method files for each of the given subclasses, while also replacing the category/subcategory/classanchor fields in the files. The end goal would be to have these steps executed by the ./processingrefBuild.sh sound step, so that processing-website/content/references/translations/*/sound/ is populated accordingly.

This dumb per-file approach using sed works quite well, the only problem is that the superclass methods which are copied after the actual doclet generation obviously don't show up under the "methods": [] of the subclass json files. I could probably fudge something together to also copy over the method description into the subclass-files, but maybe you have a better/nicer idea of how this could be done..?

#!/bin/sh

cd "`dirname $0`/content/references/translations/en/sound/"
npx prettier --write .

function CopyAndReplace ()
{
    # remove class file which was only needed to trigger generation of the per-method .json files
    rm "$superclass.json"

    echo "$superclass"
    for infile in $superclass*; do
        # for every _method_.json: create a copy for very subclass
        echo " - $infile"
        for subclass in $subclasses; do
            outfile=`echo $infile | sed "s/$superclass/$subclass/"`
            if [ -f $outfile ]; then
                echo "   . $outfile already exists, subclass must have its own @webref documentation"
            else
                echo "   > $outfile"
                # change @webref (sub)categories
                if [ "$superclass" = "SoundObject" ]; then

                    # fix discrepancy between class name and webref category name
                    prettyclass=$subclass
                    if [ "$subclass" = "Oscillator" ]; then
                        prettyclass="Oscillators" # fix category name
                    elif [ "$subclass" = "AudioIn" ]; then
                        prettyclass="I/O"
                    fi

                    sed -e "s,\"category\": \"SoundObject\",\"category\": \"$prettyclass\"," \
                            -e "s/\"subcategory\": \"\"/\"subcategory\": \"$subclass\"/" \
                            -e "s/\"classanchor\": \"$superclass\"/\"classanchor\": \"$subclass\"/" \
                                $infile > $outfile
                else
                    # all concrete classes simply replace the subcategory
                    sed -e "s/\"subcategory\": \"$superclass\"/\"subcategory\": \"$subclass\"/" \
                            -e "s/\"classanchor\": \"$superclass\"/\"classanchor\": \"$subclass\"/" \
                                $infile > $outfile
                fi
            fi
        done
        rm "$infile"
    done
    echo
}

superclass=SoundObject subclasses="AudioIn Noise Oscillator" CopyAndReplace

superclass=Oscillator subclasses="Pulse SawOsc SinOsc SqrOsc TriOsc" CopyAndReplace
superclass=Noise subclasses="BrownNoise PinkNoise WhiteNoise" CopyAndReplace
superclass=Effect subclasses="AllPass BandPass Delay HighPass LowPass Reverb" CopyAndReplace
superclass=Analyzer subclasses="Amplitude BeatDetector FFT Waveform" CopyAndReplace

cd `dirname "$0"`

[fdoflorenzano]

Hey @kevinstadler!

I went over this for a little bit, but to be honest it's a bit hard cause it's been a while and I'm not familiar with the conventions (if there are any set) that processing uses for their reference declaration. So I'm unsure whether these are special cases to take care of, or more of a general extension.

My intuition is that the current doclet script should be able to handle this more easily, since you get access to a Class' declarations and all. I don't remember getting into any inheritance stuff (cause the original doclet didn't either), but I'm guessing there should be a way of doing this with the new weblet API.

I also remember there were certain sections in the doclet that handled special cases for certain libraries, so maybe it's fine and the ClassWritter class could have a special section for these sound library cases.