[CAUSEWAY-2526] Tooling: suppress header, use filename in caption

• Type: Improvement
• Status: Resolved
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 2.0.0-M5
• Component/s: Docs & Website
• Assignee: Daniel Keir Haywood
• Reporter: Daniel Keir Haywood
• Created: 04/Feb/21 07:02
• Updated: 07/Feb/21 14:58
• Resolved: 07/Feb/21 14:55

Description

The generated index includes a header, but that makes it tricky to include.  

For example, this source:

 

Renders as folows:

 

I think that the "AcceptHeaderService : interface" is unnecessary (there would normally be a paragraph here anyway if there was some javadoc for the class).

It would be nice though to use the class as a caption:

[source,java]
.AcceptHeaderService.java
----
public interface  AcceptHeaderService {
   ...
}
----

 

Extending the idea... 

I think it might be useful to include "API" as a section, but after the top-level paragraph.

In other words, the generated file would be:

The paragraph(s) taken from the javadoc of the class interface.

There might be quite a lot of text here.

= API

[source,java]
.AcceptHeaderService.java
----
public interface AcceptHeaderService {
  ...
}
----

 

These generated files will then be included quite nicely into the refguide pages.