[MDSAL-301] Rework javadoc generation in bindings Created: 25/Jan/18  Updated: 27/Mar/18  Resolved: 27/Mar/18

Status: Resolved
Project: mdsal
Component/s: Binding codegen, Binding V2 codegen
Affects Version/s: None
Fix Version/s: Oxygen SR1

Type: Epic Priority: Medium
Reporter: Robert Varga Assignee: Robert Varga
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Epic Name: YANG javadoc snippet optimization

 Description   

This is a top-level tracker issue, which will need to be addressed in mdsal-binding-generator-impl and in mdsal-binding2-generator-impl.

The code here is twisted and inefficient, causing huge memory usage for strings during code generation, especially with large models.

Two things need to happen:

  • YANG snippet needs to be generated and filtered as a CharSource, e.g. lazily, without instantiating the full thing before the class is actually output
  • Snippet generation needs to work on top of org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement view of the world, so that 'uses' are not expanded, but rather the snippet quotes the actual YANG text

 

 Comments   
Comment by Robert Varga [ 07/Feb/18 ]

Actually CharSource is rather inefficient and needlessly complex. The class exposing a YANG text snippet is coming in yang-model-export-2.0.2 and it has the shape of Iterable<String>, which is perfectly fine. It will need to be integrated once we adopt yangtools-2.0.2.

Comment by Robert Varga [ 07/Feb/18 ]

binding v1 use of YangTextSnippet: https://git.opendaylight.org/gerrit/68031

binding v2 use of YangTextSnippet: https://git.opendaylight.org/gerrit/68032

 

Comment by Robert Varga [ 07/Feb/18 ]

As it turns out, these two patches end up slimming our runtime support jars by ~260kB.

Comment by Robert Varga [ 14/Feb/18 ]

Picking this up once again, this actually is a fault at how YANGTOOLS-193 was implemented. It confused DocumentedType.getDescription() and GeneratedType.getComment() – the two have differing semantics and getComment() is actually unused. It is the latter method which should encapsulate enough data to reconstruct the javadoc.

Comment by Robert Varga [ 14/Feb/18 ]

https://git.opendaylight.org/gerrit/68191 moved the template code, creating an abstract layer to make the old structure work – this needs to be followed-up with cleaning up the API and eliminating the unneeded layer.

Comment by Robert Varga [ 14/Feb/18 ]

https://git.opendaylight.org/gerrit/68254 cleans the entire mess up, so that we properly capture state and push it towards the templates.

Comment by Robert Varga [ 14/Feb/18 ]

JieHan2017 can you port last two patches to binding V2, please?

Comment by Jie Han [ 15/Feb/18 ]

Yes, I will.

Comment by Jie Han [ 24/Feb/18 ]

Ported to binding v2 master:
https://git.opendaylight.org/gerrit/68657

Generated at Wed Feb 07 20:09:27 UTC 2024 using Jira 8.20.10#820010-sha1:ace47f9899e9ee25d7157d59aa17ab06aee30d3d.