Changes between Version 11 and Version 12 of Documentatie/Ontwikkelaar/Omgeving/IDE

Timestamp:

12/18/15 10:01:13 (10 years ago)

Author:

adriaan

Comment:

--

Documentatie/Ontwikkelaar/Omgeving/IDE

@@ -75 +75 @@
 
 Om automatisch documentatie te kunnen genereren moet je de docstrings op een bepaalde gebruiken.
-Stel je de setting van !PyCharm op deze manier in, dan genereert hij de juist format.
+Stel je de setting van !PyCharm op deze manier in, dan genereert !PyCharm het juiste format.
 
 [[Image(docstring.png)]]
+
+De docstrings die zo gegenereerd worden, maken gebruik van `@param` en `@return`. Daarnaast kan je ook type-informatie opnemen, zodat !PyCharm betere autocomplete kan bieden. Een typisch stuk documentatie ziet er zo uit:
+
+{{{
+def friemel(iets, extra=False):
+    """
+    Beschrijving wat `friemel()` doet, in algemeen leesbare
+    termen. Als friemelen al een zelfbeschrijvende functienaam
+    is, dan hoeft daar niet veel te staan. Zet Trac-style code-
+    markers om functieaanroepen. Als je naar de parameter @p iets
+    verwijst in de lopende tekst, zet er dan @p voor. Dat is niet
+    standaard epytext, wel Doxygen-style. Je kan met @return een
+    type opgeven, zodat PyCharm automatisch type-informatie heeft
+    daar waar je `friemel()` gebruikt.
+
+    @param iets:
+        Schrijf een langere uitleg over de parameter @p iets.
+        Precondities, of verwacht gebruik. Als je een specifiek
+        type verwacht voor @p iets, kan je de @type annotatie
+        gebruiken -- dat helpt PyCharm ook in autocomplete.
+    @type iets: list[int]
+    @return: list[float]
+    """
+}}}