`update` and `require` properties for AA

[Seb]

On Wednesday, 27 June 2018 at 13:41:46 UTC, Jacob Carlborg wrote:
> On 2018-06-27 01:22, Seb wrote:
>> On Tuesday, 26 June 2018 at 17:12:37 UTC, H. S. Teoh wrote:
>>> On Tue, Jun 26, 2018 at 12:54:11PM -0400, Steven 
>>> Schveighoffer via
>>> Digitalmars-d wrote: [...]
>>>> 1. The dlang.org repository is backwards -- master generates 
>>>> the docs
>>>> for the default dlang.org. I've brought this up before, 
>>>> still don't
>>>> understand why we don't use stable for the latest dlang.org.
>>>
>>> Probably because we want to keep phobos-prerelease up-to-date 
>>> with git
>>> master?
>>
>> FWIW the docs in the release archives are built from stable.
>> The reason is that both stable _and_ master are built on 
>> dlang.org, so
>> historically no one was interested in doing release management 
>> for the
>> docs.
>>
>>> The only sane way to do this IMO is to make the dlang.org 
>>> makefiles
>>> generate multiple versions of the docs, thereby acting as the
>>> authoritative source for all dlang.org pages.
>>
>> It already takes 20 minutes to do a full build of all 
>> dlang.org HTML pages.
>> Doing it for old versions is a REALLY bad idea as you are 
>> susceptible to
>> - more random failures (e.g. DUB registry being down)
>> - it will take hours for each build
>> - it won't be possible to do it in a CI for each PR due to the 
>> large
>> time required, which means the deployment could be broken 
>> without us
>> knowing
>> - resources might be offline or change (e.g. currently it 
>> fetches the
>> RSS from the DBlog for the frontpage indexes, this already 
>> broke the
>> build a few times)
>> - building all versions will fail due to newer dependencies or 
>> OS-level
>> changes (e.g. -fPIC, glibc changes, ...)
>
> An alternative would be to specify for each symbol when it was 
> introduced. A simple way would be to just add it to the 
> documentation. Or it could be added as a UDA, this would be 
> more flexible. If the current docs now which version itself is 
> it could add an option to filter out symbols for a given 
> version.
>
> Having it as a UDA could also give other future advantages. For 
> example, when building applications on macOS, Apple recommends 
> always using the latest SDK even when deploying to older 
> version of the OS. Symbols are annotated with in which version 
> of the OS they were introduced. Then the compiler will give an 
> error/warning if using a symbol without the proper guards and 
> deploying to an older version of the OS. Not sure if this would 
> be interesting to us but it shows using a UDA could have 
> advantages.

If someone wants to build sth like this, this should be easily 
doable without attributes as we have DMD's json Output for each 
phobos version:

https://github.com/dlang/docarchives.dlang.io/blob/master/archives/v2.080.0/docs-latest.json

Ddox uses this file to generate its entire documentation, so just 
iterating over the json files and checking in which json file a 
specific symbol stops to appear shouldn't be too hard to automate.
The harder bit is to integrate this aggregated information with 
the actual docs, but in the worst case we can always fallback to 
a bit of JavaScript (and we have a custom preprocessor for ddoc 
too).
Of course an aggregator could also edit Phobos directly, s.t. all 
this work doesn't need to be done by hand...