POC: Automatically add description from schema when available

[drdavella]

This is a prototype of an idea that @perrygreenfield proposed for automatically adding description fields from schemas to the associated nodes of ASDF files when they are written. It should not be merged as-is, but does demonstrate proof-of-concept.

I think we might want to add a class attribute to asdf.types.ExtensionType that controls whether the description field should be written or not. It can be set to False by default but child tag implementations can override it.

This could also make it possible to populate descriptions contained in an ASDF file into the in-memory representation of the tree, where it could then be accessed by tools.

[stsci-bot[bot]]

Hi there @drdavella :wave: - thanks for the pull request! I'm just a friendly :robot: that checks for issues related to the changelog. I help make sure that this pull request is milestoned and labeled correctly. This is mainly intended for the maintainers, so if you are not a maintainer you can ignore this, and a maintainer will let you know if any action is required on your part :smiley:.

Everything looks good from my point of view! :+1:

If there are any issues with this message, please report them here.

[stsci-bot[bot]]

Hi there @drdavella :wave: - thanks for the pull request! I'm just a friendly :robot: that checks for issues related to the changelog. I help make sure that this pull request is milestoned and labeled correctly. This is mainly intended for the maintainers, so if you are not a maintainer you can ignore this, and a maintainer will let you know if any action is required on your part :smiley:.

Everything looks good from my point of view! :+1:

If there are any issues with this message, please report them here.

[drdavella]

If we intend to support this, we need to add something to the standard to codify this convention. I propose adding a reserved attribute like $description (in the same vein as $ref) in order to make sure we don't collide with other potential attributes.

[perrygreenfield]

It would be good to illustrate this with an example showing when it would be automatically used to add a description field. It certainly would be important to be able to indicate whether or not it should be propagated to the asdf file. I can also see a need for two different description fields in the schema. One more detailed on for those reading the schema, and one as a comment to be used in the asdf file. I'm not sure if this would support that.

[codecov[bot]]

Codecov Report

Merging #664 into master will increase coverage by 0.01%. The diff coverage is 100%.

@@            Coverage Diff             @@
##           master     #664      +/-   ##
==========================================
+ Coverage   93.24%   93.26%   +0.01%     
==========================================
  Files          39       39              
  Lines        4295     4307      +12     
==========================================
+ Hits         4005     4017      +12     
  Misses        290      290

Impacted Files	Coverage Δ
asdf/types.py	95.62% <100%> (+0.23%)	:arrow_up:
asdf/schema.py	94.25% <100%> (+0.08%)	:arrow_up:

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 0c72145...3c5a6a0. Read the comment docs.

[WilliamJamieson]

Closing. This has become very stale