Testing @tags

After a brief study of Doctum's default theme, I've discovered a few interesting things.

First, most of the method/parameter/class descriptions have been shortened.

The theme implements a shortdesc and longdesc parameter on most objects, and prefers the shortdesc in most cases. The short desc is just the summary line, and the longdesc is the summary line and the description body.

In my latest commit, I've forked the theme, changed the header color (just to prove to myself that the custom theme worked), and preferred the longdesc in classes / interfaces / and general docs pages (they all appear to use the class.php template).

Here is my latest artifact site: https://project.pages.drupalcode.org/-/doctum_documentation/-/jobs/13339...

I've also discovered that the twig theme implements a tags() method that most of Doctum's documentable objects implement.

For example, @see tags get implemented in the documentation for a specific parameter or method as a popover that shows you the other class, method, or whatever that is being referenced. Here's an example: https://project.pages.drupalcode.org/-/doctum_documentation/-/jobs/13339...

Here is another example that is an actual link to that spot in the code: https://project.pages.drupalcode.org/-/doctum_documentation/-/jobs/13339...

The actual method call and twig code looks like this

{% if method.tags('see') %}
  {{ block('see')}}
{% endif %}

{% block see %}
    <table class="table table-condensed">
        {% for see in method.getSee() %}
            <tr>
                <td>
                    {% if see[4] %}
                        <a href="{{see[4]}}">{{see[4]}}</a>
                    {% elseif see[3] %}
                        {{ method_link(see[3], false, false) }}
                    {% elseif see[2] %}
                        {{ class_link(see[2]) }}
                    {% else %}
                        {{ see[0]|raw }}
                    {% endif %}
                </td>
                <td>{{ see[1]|raw }}</td>
            </tr>
        {% endfor %}
    </table>
{% endblock %}

As for these other tags, I'm getting the impression that their content is accessible via the same interface and may be awaiting implementation.

So for our purposes, I strongly think we should be exploring subtheming the default doctum theme to take advantage of some of the behavior we're looking for.

I can confirm that there are some instances of {@inheritdoc} that are pointing all the way up to the highest level class, and that class just has {@inheritdoc} on a method that is not inherited.

The __sleep method on the DependencySerializationTrait is a good example.

https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Dependenc...

It's comment in the code is just a plain {@inheritdoc}, even though it inherits nothing.

Here it is in our doctum docs:

https://project.pages.drupalcode.org/-/doctum_documentation/-/jobs/13339...

And here is the Drupal AnnounceBlock __sleep method inherited from the trait.

https://project.pages.drupalcode.org/-/doctum_documentation/-/jobs/13339...

The current API docs just print nothing when this is the case. I think that works for making it "presentation ready", but it hides the issue. I'd like for doctum to print out a log of all of the instances where this happens so we can track them down and fix the source code.

I've done some deeper research and found out the extant of Doctum's tag detection abilities.

Doctum implements a DocBlockParser class that uses phpDocumentor as a backend, and it specifically calls this list of Reflection utilities for detecting and parsing tags .

use phpDocumentor\Reflection\DocBlock\Tags\Author;
use phpDocumentor\Reflection\DocBlock\Tags\Covers;
use phpDocumentor\Reflection\DocBlock\Tags\Deprecated;
use phpDocumentor\Reflection\DocBlock\Tags\Generic;
use phpDocumentor\Reflection\DocBlock\Tags\Param;
use phpDocumentor\Reflection\DocBlock\Tags\PropertyRead;
use phpDocumentor\Reflection\DocBlock\Tags\Property;
use phpDocumentor\Reflection\DocBlock\Tags\PropertyWrite;
use phpDocumentor\Reflection\DocBlock\Tags\Return_;
use phpDocumentor\Reflection\DocBlock\Tags\See;
use phpDocumentor\Reflection\DocBlock\Tags\Throws;
use phpDocumentor\Reflection\DocBlock\Tags\Var_;
use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag;
use phpDocumentor\Reflection\DocBlock\Tags\Link;
use phpDocumentor\Reflection\DocBlock\Tags\Since;
use phpDocumentor\Reflection\DocBlock\Tags\Uses;
use phpDocumentor\Reflection\DocBlock\Tags\Version;

The tags that the default theme actually uses is even smaller, which backs up my hunch that we can do some twig themeing to get even more into the documentation.

From docum's default theme "class.twig" template:
(note, I'm pretty sure this isn't the full tags implementation, some other docblock tags are obviously elsewhere because they're visible on the frontend, but we just haven't found the entrypoint yet)

<div class="tags">
            {% if method.parameters %}
                <h4>{% trans 'Parameters' %}</h4>

                {{ block('parameters') }}
            {% endif %}

            {% if method.hintDesc or method.hint %}
                <h4>{% trans 'Return Value' %}</h4>

                {{ block('return') }}
            {% endif %}

            {% if method.exceptions %}
                <h4>{% trans 'Exceptions' %}</h4>

                {{ block('exceptions') }}
            {% endif %}

            {% if method.tags('see') %}
                <h4>{% trans 'See also' %}</h4>

                {{ block('see') }}
            {% endif %}

            {% if method.hasExamples() %}
                <h4>{% trans 'Examples' %}</h4>

                {{ block('examples') }}
            {% endif %}

One of the more interesting classes is the so called "Generic" tag.

According to phpDocumentor, the Generic tag detects unknown tags in a docblock, even if it isn't otherwise formally recognized or represented by another class. My hope is that some of the below "unimplemented" tags will fall under this list.

Not even phpDocumentor has all of the tags we're looking for, so I suspect that this "generic" tag may hold the tag content that isn't found elsewhere.

Here's even a list of the "officially" supported phpDocumentror tags, and most of the ones we want aren't on there.

https://docs.phpdoc.org/guide/references/phpdoc/tags/index.html

So here is an updated list showing the implementation status of each tag that we want to target.

• @code/@endcode - not implemented by doctum, may be generic
• @defgroup, @addtogroup, @ingroup - not implemented by doctum, may be generic
• @Event - not implemented by doctum, may be generic
• @file - not implemented by doctum, may be generic
• @inheritdoc - is implemented via an unknown mechanism (re: our research), sometimes top-level classes use @inheritdoc when nothing is inherited, and that error flows into its children. Can be overridden in the theme.
• @link - is implemented by doctum, not by the theme
• @mainpage - not implemented by doctum, may be generic
• @param - is implemented by doctum, and implemented by the theme (via a "parameters" parameter on some objects). Typehints look like they may need some work. Possibly some theming will expose this more.
• @Annotation, @Plugin - not implemented by doctum, possibly generic
• @ref - not implemented by doctum, possibly generic
• @return - is implemented by doctum, and visible on the frontend, may need a little work to get right
• @section, @subsections - not implemented by doctum, possibly generic
• @see - is implemented by doctum, theme, and phpDocumentor official tags
• @throws - is implemented by doctum, present in theme, may need work to get the description
• @todo - Apparently the text appears, but not the tag saying that it is a todo item
• @var - is implemented by doctum, not implemented by theme

A lot of these fall under the "maybe the generic class gets them" so I think it's worth digging into this to be sure. If the generic class doesn't pick them up and we can't see the tag content from the frontend, we'll have to start looking into customizing or contributing to doctum.

As for the rest, I see about ~7 tags that Doctum does natively support that probably can be fixed by themeing.

This comment on another issue here on Doctum Documentation is relevant to the follwing tags:

https://www.drupal.org/project/doctum_documentation/issues/3635194#comme...

• @defgroup
• @ingroup
• @link, @endlink
• @addtogroup

As a concept, grouping allows you to link different parts of your docs up to one another under one "group" umbrella.

However, the current Drupal API docs are currently using *api.php files to host our @defgroup definitions and documentation. Since these are going away, they're not a stable target for building a grouping feature around. I feel that the grouping features (as we know them) should be deferred until the migration away from *.api.php has gotten underway and we can point people to a static URL on that microsite.

There's no reason why we couldn't build a group page generation process, that lists everything in that group as a table, perhaps, but that feature is practically useless unless there is content on that group page explaining what the group is, and that is precisely the information that is being stripped from *.api.php files in favor of markdown.

My guess is that the proclivity of *.api.php files in core sprung up precisely because conceptual grouping exists in documentation tools, and that feature almost always expects to find a single file somewhere in your code base that explains everything there is to know about that concept.

Hence, the predicament we're in now.

@todo tags are resolved in the latest build:

Job info: https://git.drupalcode.org/project/doctum_documentation/-/jobs/13409920

Link to docs website: https://project.pages.drupalcode.org/-/doctum_documentation/-/jobs/13409...

Apparently it's just a setting you can pass into the config file and the theme takes care of rendering it properly.