search

adobe / hyde

A front-end to Jekyll that parses C++ sources to produce and enforce out-of-line documentation
http://opensource.adobe.com/hyde/
MIT License
323 stars 41 forks source link

Add tested_by functionality #54

Closed baheath closed 4 years ago

baheath commented 4 years ago

Adds an optional tested_by documentation element to function documentation. This support is off by default and can be enabled with a command line argument or in the config file, as either an optional or required element. The element value is required to be an array of strings, or one of the supported tags (__OPTIONAL__, __MISSING__), depending on enablement category.

Also adds support for outputting the emitted/reconciled documentation as JSON so it can be consumed by other tools.

baheath commented 4 years ago

Sorry about all the closing and reopening. Finally got the CLA check to pass.

jaredwy commented 4 years ago

I am curious why yaml now has to know about json output? Are there operations only happening in the yaml output that we could push to operate on the json structures so that YAML becomes thinner

baheath commented 4 years ago

I am curious why yaml now has to know about json?

@jaredwy The goal of this is to be able to tag a particular API with the tests for it. That all works fine within the yaml. But then we also want to be able to parse out the test info to be able to generate coverage reports, etc. Ideally I wanted to just have hyde do:

  1. Parse yaml
  2. Convert to json
  3. Output the json

However, the way hyde is currently architected, several things are intertwined:

  1. Needs to parse the headers (c++) in order to parse the yaml files
  2. All the logic for reading the yaml and converting to json is within the do_merge/reconcile methods of the yaml emitter classes

So, I decided to add an out parameter to the emit methods to capture the result of that parsing/converting logic.

I am certainly open to other options.