Dev Faq
10
votes

Les étiquettes d'argumentation avant les paramètres dans les fonctions - Bug possible dans Swift Markup?

J'ai la fonction suivante dans une classe: xxx

appelé comme suit laisser myweather = conditions (pour: myLocation) << p> Le code fonctionne bien, la question concerne la documentation. L'image ci-dessous est ce qui est vu dans la fenêtre "Aide rapide" pour la fonction . Étant donné que l'utilisateur de la fonction doit utiliser l'étiquette d'argument externe ( pour ) et que j'ai explicitement documenté cette étiquette, ne devrait pas la ligne de paramètres dans la fenêtre d'aide rapide Lire les paramètres pour et pas paramètres emplacement ?

est-ce un bogue en Xcode ou y a-t-il une raison pour laquelle le nom du paramètre (interne) est affiché et non l'étiquette d'argument externe? < / p>

Entrez la description de l'image ici

4 commentaires

J'ai toujours trouvé qu'un peu étrange, mais je suppose que le "nom de paramètre externe" agit comme une étiquette pour le site d'appel et le "nom de paramètre interne" comme le nom réel nom . L'étiquette est censée rendre l'appel de fonction lire un peu comme une phrase ou une phrase. Dans Swift 3 Conventions, ces étiquettes sont régulièrement des prépositions au lieu de noms, et il serait logique de décrire les paramètres par leur nom (généralement un nom) au lieu d'une étiquette (qui peut être une préposition). Si ma supposition a raison, je préférerais - pour la clarté - ils utilisaient "l'étiquette" et "nom" au lieu de nom "externe" et "interne".

Xcode devrait vraiment être capable de produire deux version de la documentation. Un pour les consommateurs de l'API sans accès au code source, indiquant le nom externe uniquement dans la ligne de déclaration et à l'aide du nom externe de la description du paramètre. Et un autre pour le mobilier de la méthode, montrant les deux noms dans la déclaration et en utilisant le nom interne dans la description du paramètre. Je ne pense pas que Xcode puisse distinguer ces deux vues.

@Codo, je suis enclin à être d'accord mais de doute que cela se produirait jamais. Pendant ce temps, j'ai soulevé cela comme un bogue (27921906). Je vais mettre à jour ici avec n'importe quelle réponse.

Je le vois aussi principalement comme un bug. Si Xcode ne fournit pas à la fois une vue interne et externe, il doit indiquer la vue externe, n'utilisez donc que le nom du paramètre pour dans votre code.

3 Réponses :

0
votes

Le mot "for" n'est pas un mot obligatoire, il est facultatif pour une meilleure compréhension du code, lorsqu'il est utilisé.

dans le swift 3 Stands de livre:

L'utilisation des étiquettes d'argumentation peut permettre une fonction à appeler dans une manière expressive, de type phrase , tout en fournissant un organe de fonction lisible et clair dans l'intention .

Sans ce mot, écrire le code serait xxx

lorsque nous définissons des méthodes, il convient toujours d'utiliser des mots comme avec :, Utilisation de :, pour :, withLabel: etc.

4 commentaires

Je suppose que Vince O'Sullivan veut corriger la documentation et ne pas changer la signature de sa méthode. Cela ne répond pas vraiment.

Mais je ne comprends pas pourquoi allions-nous remplacer le mot "emplacement" dans la documentation du mot "pour". S'il s'agit de paramètre, il devrait représenter le mot que nous utilisons dans le code comme une variable, n'est-ce pas?

Il a demandé "si les paramètres ne sont pas la ligne de paramètres dans la fenêtre d'aide rapide de lire les paramètres de lecture et non des paramètres", c'est pourquoi je mets la réponse avec la marque d'arguments.

Même si l'étiquette peut être et est omise dans l'appel, le paramètre nécessite toujours un nom dans la documentation. Pour les appelants de la méthode, le prénom s'applique, c'est-à-dire pour dans ce cas. C'est ce que l'on pourrait attendre dans la documentation. Le deuxième nom ( emplacement dans ce cas) est le nom interne utilisé par la mise en œuvre de la méthode. Il devrait être caché pour les consommateurs.

0
votes

Si vous souhaitez que la documentation soit affichée, vous devez afficher en commentaire comme suit: xxx

Entrez la description de l'image ici

2 commentaires

Sous Parameters, il est indiqué "pas de description", le nom interne Emplacement est visible deux fois et la description du paramètre apparaît désormais comme une balle des descriptions générales. C'est encore pire que la sortie originale et certainement pas ce que Vince O'Sullivan cherchait.

Étant donné que la balle de description utilise le composé de paramètres Label +, et la section des paramètres décrit uniquement l'emplacement ... Je ne sais pas ... pour moi, la documentation est claire.

1
votes

Tout simplement, pour n'est pas le paramètre; emplacement est. Et l'aide rapide documente les paramètres.

Préférer cette aide rapide à identifier pour en tant que lieu de la surface de la Terre, comme cela a été suggéré, serait un peu déroutant du lecteur.

the splg et Directives de conception de l'API Utilisez la terminologie "Paramètre" et "L'étiquette d'argument" (comme dans votre question titre) au lieu de "paramètre interne" et "paramètre externe" (qui peut conduire à la confusion que vous élevez). Compte tenu de cela, les paramètres relèvent des paramètres en direction de l'aide rapide et des étiquettes d'argumentation apparaissent dans la déclaration.

0 commentaires

Articles qui pourrait vous intéresser :

Comment corriger l'erreur "Hash mismatch for chunk" avec iOS 13 + Apple On Demand Resources
SwiftUI: la fenêtre contextuelle d'édition structurée (Commande + clic) ne s'affiche pas
La construction de Xcode échoue en raison d'un symbole non défini: __swift_FORCE_LOAD _ $ _ swiftUIKit
Problème de périphérique Xcode - Échec de la vérification _shouldMakeReadyForDevelopment même si le périphérique n'est pas verrouillé par mot de passe