search

Azure / autorest.java

Extension for AutoRest (https://github.com/Azure/autorest) that generates Java code
MIT License
33 stars 82 forks source link

partial-update, support partial update on class/interface's Javadoc #2502

Open haolingdong-msft opened 9 months ago

haolingdong-msft commented 9 months ago

Background

The customized class level javadoc is ignored and removed after next codegen. Link https://github.com/Azure/autorest.java/issues/2492

We will need to support partial update for class level javadoc. Similar as supporting partial-update on class's implemented types, we do not need to add Generated annotation to class, as this is ambiguous.

Design

Instead of adding the @Generated annotation. I plan to use below syntax to specify the generated part of class level javadoc. And every codegen will overwrite the part between <!-- start generated doc --> and <!-- end generated doc --> to the newly generated one.

This logic is applied in partial-update for package-info.java already, code.

/**
 * Some other custom Javadocs which shouldn't be overwritten as they aren't contained in the generated Javadoc block.
 * <p>
 * <!-- start generated doc -->
 * Package containing the implementations for AutoRestSwaggerBatService.
 * Test Infrastructure for AutoRest Swagger BAT.
 * <!-- end generated doc -->
 */

Link partial update on javadoc for client methods: https://github.com/Azure/autorest.java/issues/2510

weidongxu-microsoft commented 9 months ago

LGTM

If service does not want any generated doc, they would do this?

/**
 * Some other custom Javadocs which shouldn't be overwritten as they aren't contained in the generated Javadoc block.
 * <p>
 * <!-- start generated doc -->
 * <!-- end generated doc -->
 */
haolingdong-msft commented 9 months ago

<!-- start generated doc --> and <!-- end generated doc --> is added by codegen. If there is no generated javadoc, we will not add it.

weidongxu-microsoft commented 9 months ago

We can release a version with start/end but without update in partial-update logic, to refresh existing libs. Then another version with partial-update logic.

haolingdong-msft commented 9 months ago

Yes, I plan to do so as well.

We can release a version with start/end but without update in partial-update logic, to refresh existing libs. Then another version with partial-update logic.

srnagar commented 9 months ago

Do we plan to support multiple start and end tags?

For example, can this be supported?

/**
 * Some other custom Javadocs which shouldn't be overwritten as they aren't contained in the generated Javadoc block.
 * <p>
 * <!-- start generated doc -->
 * <!-- end generated doc -->
 * 
 *  Some more custom docs added in the middle.
 * 
  * <!-- start generated doc -->
 * <!-- end generated doc -->
 */
srnagar commented 9 months ago

We will need to support partial update for class level javadoc.

We should also support partial update for all javadocs. We will have codesnippets added to javadocs of client methods too. So, we should support this wherever we have javadocs.

haolingdong-msft commented 9 months ago

currently if service team remove the @Generated annotation on client method, and update javadoc, we will keep the javadoc they updated. But at class level, it does not have @Generated annotation, so we don't do the same thing.

weidongxu-microsoft commented 9 months ago

We will need to support partial update for class level javadoc.

We should also support partial update for all javadocs. We will have codesnippets added to javadocs of client methods too. So, we should support this wherever we have javadocs.

client method issue here https://github.com/Azure/autorest.java/issues/2510

or you prefer we do them together?