Add command-line option to set the minimum access control to document

[jpsim]

--minimum-access-control [public | internal | private] with public as default

[beltex]

So currently it is expected behaviour that private entities (enums, structs, etc.) will show up in the doc by default correct?

[segiddins]

@beltex yes, that is correct.

[beltex]

Cool, thanks @segiddins!

[segiddins]

@jpsim the easiest way to do this would be if SourceKitten could just add an ACL to its output for each token, but I don't know if SourceKit exposes that information.

[jpsim]

@segiddins sourcekitten already exposes ACL information, i.e.:

"key.attributes" : [
  {
    "key.attribute" : "source.decl.attribute.private"
  },
  {
    "key.attribute" : "source.decl.attribute.__raw_doc_comment"
  }
]

However, simply ignoring tokens whose access control levels are under a given threshold would make the documentation coverage number invalid, since it considers all tokens. There are two possible approaches, I think:

1. make sourcekitten return all detected tokens (documented or not) and filter them from jazzy
2. pass minimum ACL level to sourcekitten

I'm not sure which one is best, so I'll just pick the easiest one and see if it works 😉.

[segiddins]

I say approach number 1

-Samuel E. Giddins

On Dec 14, 2014, at 4:35 PM, JP Simard notifications@github.com wrote:

@segiddins sourcekitten already exposes ACL information, i.e.:

"key.attributes" : [
{
"key.attribute" : "source.decl.attribute.private"
},
{
"key.attribute" : "source.decl.attribute.__raw_doc_comment"
}
]
However, simply ignoring tokens whose access control levels are under a given threshold would make the documentation coverage number invalid, since it considers all tokens. There are two possible approaches, I think:

make sourcekitten return all detected tokens (documented or not) and filter them from jazzy
pass minimum ACL level to sourcekitten
I'm not sure which one is best, so I'll just pick the easiest one and see if it works .

—
Reply to this email directly or view it on GitHub.

[segiddins]

We only seem to get when its private, and not internal or public.

-Samuel E. Giddins

On Dec 14, 2014, at 4:35 PM, JP Simard notifications@github.com wrote:

@segiddins sourcekitten already exposes ACL information, i.e.:

"key.attributes" : [
{
"key.attribute" : "source.decl.attribute.private"
},
{
"key.attribute" : "source.decl.attribute.__raw_doc_comment"
}
]
However, simply ignoring tokens whose access control levels are under a given threshold would make the documentation coverage number invalid, since it considers all tokens. There are two possible approaches, I think:

make sourcekitten return all detected tokens (documented or not) and filter them from jazzy
pass minimum ACL level to sourcekitten
I'm not sure which one is best, so I'll just pick the easiest one and see if it works .

—
Reply to this email directly or view it on GitHub.

[jpsim]

Actually, it's much worse than that. public and private both have attributes of source.decl.attribute.private (WTF, Apple) while internal has no ACL-related attribute.

I've spoken to SourceKit people about it and there's not much motivation to fix that, so we should use an alternative mode of ACL detection.

[beltex]

Works like a charm, thanks @jpsim & @segiddins! :)