Haddock Link zu Funktionen in nicht importierten Modulen

Question

In Modul B Ich habe Dokumentation mit einem Link 'A.foo', Verknüpfung mit dem foo Mitglied des Moduls A. Im Modul A importiere ich das Modul B. Haddock macht dies als Link zu A.html#t:foo, nämlich zeigt auf die Typfoo (die nicht existiert) nicht die Funktion foo, die A.html#v:foo ist.

Warum verlinkt Haddock auf t: für Variablen, die mit einem Kleinbuchstaben beginnen? Ist das ein Fehler? Für 'A.Foo' kann ich sehen, dass es ein Typ oder ein Konstruktor sein könnte, so gibt es Namespacing-Probleme. Für foo scheint eine Variable zumindest am plausibelsten zu sein.

Gibt es eine Möglichkeit, einen Link zu fälschen? Ich schreibe dies in Codebeispielen, also muss es als foo gerendert werden. Ich habe Anker versucht, aber sie rendern als Modulname, und bei direkten Hyperlinks haben Sie keine Kontrolle über den angezeigten Text.

Ich dachte über einen Postprozessor (t:[a-z] mit v: ersetzt), aber das erfordert eine benutzerdefinierte Setup.hs, die Probleme verursacht und ist ziemlich hässlich.

Ich konnte keine Haddock-Befehlszeilenflags finden, um ein vernünftigeres Verhalten zu erhalten, z. B. um anzugeben, dass foo eine Variable ist.

Ich kann keinen Import von A zu B hinzufügen, ohne zirkuläre Importe einzuführen, was zu rein für die Dokumentation hinzuzufügen ist.

Ich stoße auf dieses Problem in der , wo als Beispiel removeFilesAfter nicht die richtige Verbindung erhalten.

Answer 1

Dies war ein Haddock bug #228 und Neil Haddock bug #253 und das Update wurde für einige Monate upstream. Sie können GHC HEAD erstellen und Ihre Dokumentation neu erstellen oder auf 7,8 warten und es dann tun.

Answer 2

Ich kann die erste Frage teilweise beantworten (Warum?); nicht sicher, ob es sich um einen Fehler oder ein gewünschtes Verhalten handelt.

Wenn Schellfisch Referenzen in LexParseRn.rename löst, versucht es, die Kennung in der Umgebung (über lookupGRE_RdrName) nachzuschlagen. Das sollte scheitern. Weiter sieht es so aus, was das Ding bedeuten könnte (mit dataTcOccs from GHC’s RnEnv). Die entsprechenden Linien sind:

dataTcOccs :: RdrName -> [RdrName] 
-- Return both the given name and the same name promoted to the TcClsName 
-- namespace. This is useful when we aren't sure which we are looking at. 
dataTcOccs rdr_name 
    [...] 
    | isDataOcc occ || isVarOcc occ 
    = [rdr_name, rdr_name_tc] 
    [...] 
    where 
    occ = rdrNameOcc rdr_name 
    rdr_name_tc = setRdrNameSpace rdr_name tcName 

so gibt er den Namen zuerst interpretiert, als was auch immer es war, bevor (wahrscheinlich ein Link auf einen Wert), und dann als Typkonstruktor interpretiert. Wie kann ein regulärer Name ein Typkonstruktor sein? Meine Vermutung ist, dass dies hinzugefügt wurde, als TypeOperators in GHC 7.6 reformiert wurden, die jetzt den Namespace mit Wertelevel-Operatoren teilen.

Dann passt Schellfisch auf das Ergebnis: Wenn das erste ein Typkonstruktor ist, verwenden Sie das, andernfalls verwenden Sie das zweite. Entweder war es vorher ein Typkonstruktor, dann wird dieser verwendet. Oder war es nicht, aber dann soll die modifizierte Version dataTcOccs verwendet werden.

Es scheint mir, dass Schellfisch sollte immer nur die erste Option hier, und der Code ist nur eine irreführende Kopie davon, wie mehrere Ergebnisse verwendet werden, wenn sie tatsächlich gelöst werden können.