Annikka/evennia
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Removed a sectioning marker and updated the coding style file to be a little clearer on that.

Browse source
This commit is contained in:
Griatch 2015-03-09 08:15:44 +01:00
parent b34e8cb740
commit 1680fe6b84
2 changed files with 18 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

26
CODING_STYLE.md
View file

@ -44,9 +44,6 @@ parser will use this to create pretty API documentation.
Modules should all start with at least a few lines of docstring at Modules should all start with at least a few lines of docstring at
their top describing the contents and purpose of the module. their top describing the contents and purpose of the module.
Sectioning should not be used - the auto-api will create this
automatically. Otherwise markdown should be used as needed to format
the text.
Example of module docstring (top of file): Example of module docstring (top of file):
@ -58,6 +55,12 @@ are useful in the game ...
""" """
``` ```
Sectioning (`# title`, `## subtile` etc) should not be used in
freeform docstrings - this will confuse the sectioning of the auto
documentation page and the auto-api will create this automatically.
Use **section** with bold markers if a section is needed. Otherwise
markdown should be used as needed to format the text.
Code examples should use [multi-line syntax highlighting][markdown-hilight] Code examples should use [multi-line syntax highlighting][markdown-hilight]
to mark multi-line code blocks, using the "python" identifier. Just to mark multi-line code blocks, using the "python" identifier. Just
indenting code blocks (common in markdown) will not produce the indenting code blocks (common in markdown) will not produce the
@ -73,7 +76,7 @@ other text, only code).
The root class docstring should describe the over-arcing use of the The root class docstring should describe the over-arcing use of the
class. It should usually not describe the exact call sequence nor list class. It should usually not describe the exact call sequence nor list
important methods, this tends to be hard to keep updated as the API important methods, this tends to be hard to keep updated as the API
develops. develops. Don't use section markers (`#`, `##` etc).
Example of class docstring: Example of class docstring:
@ -148,13 +151,14 @@ Here are all the supported block headers:
``` ```
Parts marked with "freeform" means that you can in principle put any Parts marked with "freeform" means that you can in principle put any
text there using any formatting except for the indentation to mark text there using any formatting except for sections markers (`#`, `##`
which block you are part of. You should normally use the specified etc). You must also keep indentation to mark which block you are part
format rather than the freeform counterpart (this will produce nicer of. You should normally use the specified format rather than the
output) but in some cases the freeform may produce a more compact and freeform counterpart (this will produce nicer output) but in some
readable result (such as when describing an `*args` or `**kwargs` cases the freeform may produce a more compact and readable result
statement in general terms). The first `self` argument of class methods (such as when describing an `*args` or `**kwargs` statement in general
should never be documented. terms). The first `self` argument of class methods should never be
documented.
Note that Note that

2
evennia/locks/lockfuncs.py
View file

@ -12,7 +12,7 @@ with a lock variable/field, so be careful to not expect
a certain object type. a certain object type.
##Appendix: MUX locks **Appendix: MUX locks**
Below is a list nicked from the MUX help file on the locks available Below is a list nicked from the MUX help file on the locks available
in standard MUX. Most of these are not relevant to core Evennia since in standard MUX. Most of these are not relevant to core Evennia since