NEW Include properties tagged as `@config`

[dhensby]

Fixes #74

Adds private static vars (and others) that are marked as @config.

Further optional enhancements:

• [x] Ignore methods/properties tagged as @private @internal (I believe we use that to indicate an API is not "public" and so outside bounds of semver
• [x] Group configs into a separate section of the page (rather than under properties)

I'm currently looking into grouping configs separately to properties, I'm 50/50 on whether it's going to be possible it's done :)

[dhensby]

Added "config options" section :)

[dhensby]

I guess the only question left is should we include all private static variables or just the ones marked as @config?

[robbieaverill]

I guess the only question left is should we include all private static variables or just the ones marked as @config?

I think the ones marked as config would be fine. It's a practice we're trying to encourage right, even though any private static will work as a config prop

[dhensby]

I think the ones marked as config would be fine. It's a practice we're trying to encourage right, even though any private static will work as a config prop

I'm concerned that in 3.x we are not so good at tagging vars as @config...

[robbieaverill]

True. To be fair, I guess the cases where we're using private statics that aren't supposed to be config props would be lower than the cases of private statics that are but don't have the tag...

[dhensby]

Agreed - ok, well this could be merged as is and I'll add another PR to add all private static properties or I'll add it in my tomorrow to this PR

[robbieaverill]

Will deploy to UAT now

[sminnee]

@dhensby I would recommend instead that it would be best to force that we mark things as @config rather than picking up all private statics.

• Improvement of the SS4 docs is more important than SS3 docs, given where we are in SS3's lifetime.
• Including all private statics might very well include things that aren't designed to be use as config settings, meaning that the documentation would become misleading. False positives in docs (you said that this is a setting but it's not) are far more confusing than false negatives.
• Adding @config to the code will make the code more self-documenting too.

If we want a compromise, I would suggest that we show all private statics only for our SS3 docs, and not for SS4.

---

The other thing I wanted to flag is whether we should document these as config options, rather than presenting them as private statics?

I'm not sure what that would look like but you could for example show an example yaml content, as that is how people will typically set these, or just a table that excluded the private static boilerplate with is more confusing than helpful IMO.

---

Config options

SilverStripe\Assets\File:
  singular_name: "string" 
  non_live_permissions: [ ... ] # Anyone with CMS access can view draft files
  allowed_extension: [ ... ]

---

Config options in SilverStripe\Assets\File

Config option	Type	Description
singular_name	string
non_live_permissions	array	Anyone with CMS access can view draft files

[sminnee]

I forgot to say – it's awesome that our API generation tool has this level of flexibility and this is a great step forward!

[dhensby]

If we want a compromise, I would suggest that we show all private statics only for our SS3 docs, and not for SS4.

I thought about this, but there's no way (that I'm aware of at the moment) for the "filter" to know what version of code we are analysing. I'm happy to leave it as-is and not add all private static properties to config options

[dhensby]

The other thing I wanted to flag is whether we should document these as config options, rather than presenting them as private statics?

This is a good point, providing them as YAML is going to be a bit too much effort for me to justify right now, I think. especially as the type is not always known. I'll make a PR to remove the private static part.

One glaring issue with this is that the config options defined in YAML only are not presented here.

Do we want to show the default value for the options too? (if that's possible)

[dhensby]

I forgot to say – it's awesome that our API generation tool has this level of flexibility and this is a great step forward!

I credit my awesome hacking skills over how flexible the generator is ;) These changes are a bit risky as it's involved copy and pasting of parent methods in some instances... I felt it better to have slightly less stable docs code and better docs than slightly more stable docs code and less helpful docs