Short texts in ABAP Doc

[ConjuringCoffee]

ABAP Doc allows for the explicit definition of short texts and there are several ways to do so. In my opinion, it'd be a good addition to Clean ABAP to define the proper use of this feature.

As a reminder, there are three ways of defining short texts in ABAP Doc:

• <p class="shorttext">...</p>
• <p class="shorttext synchronized">...</p>
• <p class="shorttext" lang="...">...</p>

This is my proposition:

• Defining a short text for a global class in ABAP Doc is optional. The reason being that the text can be maintained in the properties of the class as well.
• If a short text for a global or local class is defined in ABAP Doc, then class="shorttext synchronized" must be used. The main reason being that it is duplicated to the description from the properties of the class otherwise. It might lead to inconsistencies in the future.
• If a short text for a method is defined in ABAP Doc, then class="shorttext synchronized" must be used. The reason being that the text is not shown in the outline in ADT otherwise. This is also true for short texts of classes in the outline and in the project explorer.

I don't have a definitive answer for the following questions:

1. If any short text is defined in ABAP Doc, should the language parameter always be provided?
2. If a text is defined for a method parameter in ABAP Doc, should it be explicitly defined as a short text?
3. If a short text is defined for a method parameter, should it be class="shorttext" or class="shorttext synchronized"?#

What is your stance on my proposition? Do you have an answer for the questions I listed?

[schmelto]

Defining a short text for a global class in ABAP Doc is optional. The reason being that the text can be maintained in the properties of the class as well.

Due to the move to ADT I suggest changing your first proposition to mandatory due I think all coding changes / documentation should be take part in one place.

Otherwise I share your opinion on your propositions.

I'm also unsure with your questions maybe someone else can share some thougts on those.

[ConjuringCoffee]

Due to the move to ADT I suggest changing your first proposition to mandatory due I think all coding changes / documentation should be take part in one place.

What do you mean exactly? ADT allows changing the class description in the "Properties" tab. I personally favor documentation in code, but I don't see much reason to enforce it here.

[schmelto]

What do you mean exactly? ADT allows changing the class description in the "Properties" tab. I personally favor documentation in code, but I don't see much reason to enforce it here.

I would recommend in documenting in the code due all changes are made in one place and you do not have to switch between perspectives to document.

[ConjuringCoffee]

About two years have passed since I've opened this issue and I've come to some conclusions about the questions I had.

If any short text is defined in ABAP Doc, should the language parameter always be provided?

I think the language parameter only makes sense to consistently use if there is no "expected" original language of objects in the system. In my opinion, this would be bad practice. The original language should always be English.

My answer therefore is: No, the language parameter doesn't have to be provided.

This is why I've been using the ABAP Cleaner's rule to automatically remove the language parameter.

This is the explanation given by the ABAP Cleaner: Removes lang="en" from the HTML tag <p class="shorttext synchronized" lang="en"> in ABAP Doc, since anyway, only the original language of the ABAP object is allowed, as defined in TADIR.

Parameter short texts

I believe it makes most sense to define them as shorttext synchronized for the same reason as for the short text of a class: Not having it synchronized can lead to potential inconsistencies.