I'm using dgeni to extract jsDoc tags from a javascript codebase and generate markdown documentation files.
Dgeni workflow relies of the concept of pipelining. In dgeni this means that you can define a list of "processors" (i.e., functions) that are run in sequence, one after the other and the output of any processor is given as input to the next one. Each processor contributes to the making of the final list of docs which gets saved to the hard disk by one of those processor (placed nearly at the end of that sequence).
E.g., this is the "default" sequence of processors when the packages base, jsdoc and nunjucks from dgeni-packages are loaded in a dgeni instance:
info: 1: reading-files (abstract) from base
info: 2: readFilesProcessor from base
info: 3: files-read (abstract) from base
info: 4: extractJSDocCommentsProcessor from jsdoc
info: 5: parsing-tags (abstract) from jsdoc
info: 6: parseTagsProcessor from jsdoc
info: 7: tags-parsed (abstract) from jsdoc
info: 8: extracting-tags (abstract) from jsdoc
info: 9: extractTagsProcessor from jsdoc
info: 10: tags-extracted (abstract) from jsdoc
info: 11: codeNameProcessor from jsdoc
info: 12: processing-docs (abstract) from base
info: 13: docs-processed (abstract) from base
info: 14: adding-extra-docs (abstract) from base
info: 15: extra-docs-added (abstract) from base
info: 16: computing-ids (abstract) from base
info: 17: computeIdsProcessor from base
info: 18: ids-computed (abstract) from base
info: 19: computing-paths (abstract) from base
info: 20: computePathsProcessor from base
info: 21: paths-computed (abstract) from base
info: 22: rendering-docs (abstract) from base
info: 23: renderDocsProcessor from base
info: 24: docs-rendered (abstract) from base
info: 25: unescapeCommentsProcessor from base
info: 26: inlineTagProcessor from jsdoc
info: 27: writing-files (abstract) from base
info: 28: writeFilesProcessor from base
info: 29: checkAnchorLinksProcessor from base
info: 30: files-written (abstract) from base
In dgeni the input/output of each processor is an array of objects, called docs, and each of those objects contains information about a given jsDoc comment found in the source files.
Dgeni provides the above default "skeleton" of processors that handle the most common needs.
For example there is one processor that extracts the jsDoc comments from the source files and saves them in the docs array and a later one reads that information and build the content to be rendered in each file, which is actually saved to the disk by even another processor... I hope gave you the idea of how dgeni works.
I do want to reuse most of what dgeni and dgeni-packages already provides, however I find myself in need of cutomizing a few behaviours.
As I already told the docs array contains one object for each jsDoc comment and the processor that writes the docs on the hard disk outputs one file for each item in this array. Instead, I need to save just one file for each javascript module in my codebase and each file must contain the information about all functions/classes/constants/etc... belonging to that javascript module (if you are not familiar with js module think of 1 module = 1 source code file).
My question is: how do I interfere/interact with the default implementation of the processors provided by dgeni?
Keep in mind that later processors may expect to find some properties/data set for each item of the docs array that have been added by previous processors.
Therefore I must be careful not to break this "contract".
Am I supposed to override only the writeFilesProcessors() with my custom logic (to obtain the desired output on the hard disk) but nevertheless forward the same docs value that I receive in input (to avoid breaking something in the processors that follows) or is there another recommended approach?
An alternative would be to completely override the computePathsProcessor() (to set the proper output file paths I need) and the renderDocsProcessor() (to aggregate the input array docs according to my custom needs) and forward a new self-made object to the following processors. Maybe even something else?