Undocumented structures should show Swift declaration

[juangamnik]

Since #129 every undocumented structure has now a text "Undocumented" like here:

But if I add some really meaningless documentation I get much more information (the Swift declaration):

So why not use the declaration instead of the meaningless notion "Undocumented" (I would just omit it).

[segiddins]

The issue here seems to be that SoureKit won't return any documentation XML when the declaration is undocumented. (See https://github.com/Realm/jazzy/blob/master/lib/jazzy/sourcekitten.rb#L97).

[juangamnik]

Uh. That's bad. But https://github.com/Realm/jazzy/blob/master/lib/jazzy/sourcekitten.rb#L96 (one line before) seems to access key.doc.full_as_xml. Perhaps there is another key, for directly accessing the declaration?

Or can the declaration documentation be directly created from the declaration info? The corresponding information should be their, shouldn't it?

[juangamnik]

Anything on this? The "Undocumented"-text is unfortunately not very informative and the "Declaration" would be very helpful.

[jpsim]

I have not worked on this functionality lately, but you're of course welcome to do so. This part of jazzy's functionality is in SourceKitten.

[juangamnik]

@jpsim: I would, but unfortunately I'm neither familiar with ruby, nor with the project itself (from the source code point-of-view). Especially, if it is not an easy one (missing information from SourceKit as @segiddins said), which needs some digging in. My first approach would perhaps be to add some whitespace fake-documentation to each undocumented declaration (or even the word "Undocumented") in transient a preprocessing step ...

[jpsim]

SourceKitten is actually 100% written in Swift. You can find the repo here: https://github.com/jpsim/SourceKitten

[juangamnik]

Oh, cool. I'll look into it as soon as I can. Thanks.

[blochberger]

Interestingly if you have a documented class declaration and an undocumented member function, then the class declaration is shown as declaration for the member function, which is just erroneous:

///
class Something {
    func doSomething() {
        …
    }
}

The class documentation will render as:

Something

class Something

and the member function declaration of doSomething() will render as:

Undocumented

Declaration

class Something

Adding an empty documentation explicitly will show the correct declaration, but will mess up documentation coverage:

///
class Something {
    ///
    func doSomething() {
        …
    }
}

[pigeondotdev]

From my understanding, this bug is related to SourceKit which is out of our hands. I've tagged the issue with blocked and I'm going to close the issue. Feel free to reopen if you disagree or have more to say about it.

[jpsim]

Not exactly out of our hands, just more work!

[pigeondotdev]

Oh okay! Sweet, my apologies.

[juangamnik]

Phew, great. Was a bit anxious, that that's it (especially as I had no time yet to look into it and it doesn't look better in the near future)

[rcbello]

Hi, I am not sure if there is already a fix on the way for this issue but I am using this fix on my copy of jazzy.
In sourcekitten.rb, I modified self.make.doc.info to

 def self.make_doc_info(doc, declaration)
      return unless should_document?(doc)

      declaration.declaration = Highlighter.highlight(
        doc['key.parsed_declaration'] || doc['key.doc.declaration'],
        Config.instance.objc_mode ? 'objc' : 'swift',
      )
      if Config.instance.objc_mode && doc['key.swift_declaration']
        declaration.other_language_declaration = Highlighter.highlight(
          doc['key.swift_declaration'], 'swift'
        )
      end

      unless doc['key.doc.full_as_xml']
        return process_undocumented_token(doc, declaration)
      end
      ...

from

 def self.make_doc_info(doc, declaration)
      return unless should_document?(doc)

      unless doc['key.doc.full_as_xml']
        return process_undocumented_token(doc, declaration)
      end

      declaration.declaration = Highlighter.highlight(
        doc['key.parsed_declaration'] || doc['key.doc.declaration'],
        Config.instance.objc_mode ? 'objc' : 'swift',
      )
      if Config.instance.objc_mode && doc['key.swift_declaration']
        declaration.other_language_declaration = Highlighter.highlight(
          doc['key.swift_declaration'], 'swift'
        )
      end
     ...

I just moved the check and handling of undocumented structure to come after adding its declaration.
I have zero experience in Ruby so I'm putting it here to see if this is the right change or if this is the right place in the code to change.

[johnfairh]

Fixed in master via #897.

[juangamnik]

Thanks!