plcli doc generate doc for files included with the importstatement

[Naheulf]

Description of the Issue

plcli doc generate doc for files included with the importstatement
WerWolv/Documentation@bc5dba2

Steps to Reproduce the Issue

Look at the doc generated by the github workflow.
For example libraries/type/color.pat.md generated from includes/type/color.pat

Expected Behavior

Each generated document file should only contain doc for elements in the source file.

Actual Behavior

The generated doc also contain doc from includes/std/core.pat and includes/std/mem.pat.

Debug Information

Edit 2024-07-13 Fix the broken link

[C3pa]

Looks like some of the links are dead, but the issue is valid. To point out more details: only the types of imported header will end up on the built docs page. For example, see the #Types section in https://docs.werwolv.net/pattern-language/libraries/std/ptr.pat which comes from: https://docs.werwolv.net/pattern-language/libraries/std/mem.pat. The functions from the imported header aren't added to the new doc page by the generator. This might be a way to resolve the issue.

[paxcut]

I think it is entirely possible that this is the intended behavior.

If a file is imported into another that means that some of its entries use one or more variables of the type in the imported file. Maybe the documentation wants to list the other types so that you can see the entire set of definitions you get when you use that one type. On the other hand this could be the an just an oversight of the handling of nested imports. I noticed this a while back and I thought it was normal.

One thing we can do is that if a header imports other headers then add an Imports From section that includes the import statements as links like this:
import std.mem;

[C3pa]

IMHO, documentation shouldn't duplicate itself. I found it quite confusing that importing std.prt also adds in std..mem.

[paxcut]

I tend to agree on it not duplicating, but I've read those pages so many times looking for specifics that it doesn't bother me anymore. The suggestion I made would eliminate the duplication while at the same time providing links to the included headers for easier browsing.

std.ptr needs std.mem to get the size of the input file if you want to use pointer relative to end of file. Since it is using a function only there is no reference to std.mem in the doc entries.