What I'd really like to see is YARD making use of the AsciiDoc header attributes. Then, it would be possible to pass data explicitly to YARD as follows:

= Normal Document Title
:yard-title: Document Title for YARD
:yard-author: The Author Name

(though it should use the implicit attributes like doctitle, author if no specific overrides are given).

This is also an interesting idea, especially that it can be considered a non-breaking change, which is important in context of #1200 (comment). I support this proposal very much, although it somewhat feels like doing Yard things with non-yard markup.

IMHO, for maximum compatibility, document meta tags should be resolved in following order of precedence:

1. Yard tags (i.e. @title, @author, etc.)
2. Yard-specific attributes* (i.e. in AsciiDoc: :yard-title:, :yard-author:, etc.)
3. Non-yard attributes* (i.e. in AsciiDoc: :doctitle:, :author:, etc. and their possible counterparts in other markups) — provided that some yet unknown configuration option is turned on; by default this option should be off for backwards compatibility
4. File name

* By "attribute" I mean AsciiDoc attributes, but also their possible counterparts in other markups, if they exist.

I think I'll find some time to implement either @mojavelinux's idea, or "2 newlines" option (see that aforementioned comment and PR #1200 as whole), or both, depending on @lsegal's opinion on this topic.

@lsegal Any opinion on @mojavelinux's idea? I believe I can implement either.

I've done some research on this topic.

How it works now

Currently, the process of YARD documentation generation is roughly like this:

1. Command line arguments are parsed. It tells which textual files should be added to YARD documentation as so called extra file objects.
2. Metadata (title, author) is extracted from extra file objects by using a few simplistic regexps.
3. Ruby and C source files are parsed, and some kind of intermediary documentation for every module and method is generated.
4. For each item to be documented (be it module, method or extra file object)
   • Generate final documentation for that item, which involves running relevant markup processor like Redcarpet, RDoc or Asciidoctor.

In this algorithm, extra file object titles must be known before step 4. begins. This is because the final documentation may contain some navigation controls, which may include links to any other extra file object. This is particularly true in case of HTML output. Consequently, document metadata cannot obtained from AsciiDoc processor (via its Asciidoctor::Document#attr API method).

What we can do about it

Option 1: Enhance regexp

Regular expressions used in step 2 can be improved to parse AsciiDoc's attribute syntax.

However, due to the complexity of AsciiDoc syntax, it is not easy to write a proper regular expression. Consider following example:

= Some Document

:arbitrary-attr: This is value for the "arbitrary-attr" attribute
:yard-title: This is value for the "yard-title" attribute

Lead paragraph

[source]
--------------------------------------------------------------------------------
:yard-title: This is just a code sample, not an attribute definition for
the current document.
--------------------------------------------------------------------------------

In the above example, /^:yard-title:/ regular expression matches twice, which is not what we want, because the last occurrence isn't actually an attribute definition.

Instead of making the regular expression more complicated, I propose adding an additional requirement: that YARD-specific attributes must be defined before the first line which is not a section title nor another attribute definition. I don't think that any fancy techniques are really needed in these attributes, therefore in my opinion such constraint is acceptable.

Option 2: Run Asciidoctor twice

Asciidoctor processor is run for the first time in step 2, and then again in step 4. The first run does not produce any output document, it is only to parse the source document and to extract YARD-specific attributes. This is a full-featured solution, which honours AsciiDoc's conditional processing, include directives, etc. No special constraints are required. Obviously some overhead is involved, but IMHO it is acceptable.

Option 3: Render contents of extra file objects earlier

Markup processors for extra file objects are run at step 2 or 3 instead of step 4. Generated output is stored in a variable and merged into template at step 4.

@mojavelinux, @lsegal, thoguhts?

The first run does not produce any output document, it is only to parse the source document and to extract YARD-specific attributes.

Asciidoctor already provides a mode to only parse the header, which is extremely lightweight. See the :parse_header_only option on this page: https://docs.asciidoctor.org/asciidoctor/latest/api/options/

Keep in mind that the header ends at the first blank line after the document title, so the attribute entries must be compacted and directly adjacent to the document title.