Constructors
Gerdus van Zyl
How do I document class constructors (def __init__)?
Also is there any support for javadoc style @todo or similar? I am
thinking along the lines of an auto generated todo list from code.
Thanks,
Gerdus
Daniel Haus
> Now that apydia works so well I am busy documenting all my code :-)
> How do I document class constructors (def __init__)?
Apydia ignores properties starting with "_", so it does with
"__init__". You can override this behavior by specifying a
"__doc_all__":
class Thing(object):
__doc_all__ = ["__init__", "method1", "method2"]
def __init__(self):
"""Thing's constructor"""
pass
That's more than ugly and I can't remember why I chose to ignore "_"-
prefixed symbols by default back then. I'm considering to change this.
> Also is there any support for javadoc style @todo or similar? I am
> thinking along the lines of an auto generated todo list from code.
No, not yet. I'm planning to implement an extension interface for
pluggable preprocessors for things like that. Suggestions, ideas and
wishes are highly appreciated!
--
Daniel Haus
http://ematia.de
Gerdus van Zyl
which is unexpected but useful.
Ignoring properties starting with "_" or "__" makes sense since it is
python convention to name non-public method starting with "__" or "_".
It's just that __init__ is the exception to the rule.
Daniel Haus
>
> __doc_all__ seems that be "only document these properties/methods"
> which is unexpected but useful.
Exactly. It's just ugly to have that inside of your classes.
> Ignoring properties starting with "_" or "__" makes sense since it is
> python convention to name non-public method starting with "__" or "_".
> It's just that __init__ is the exception to the rule.
So far that's right, but what about operator overloading, like eg.
__add__() or __eq__(), those methods should be documented by default
as well, I guess. Maybe a good way would be to document only methods
matching a "__xxx__" pattern, ignoring all other symbols like "_xxx"
or "__xxx". What do you think?
Gerdus van Zyl
implementations: __add__() or __eq__(), etc. What would be useful is
including a table of supported operators for this class, eg: "This
class implements the following operators:"
So my thinking is that operators is a different thing than methods or
properties and should be treated seperately if at all. Following that
reasoning contructors(__init__) should also be put apart/seperate but
I don't mind lumping it with methods if it is displayed first.
Some people would also like to document non-public methods, don't know
why but i'm sure there are such people. But trying to be all things to
all people is very dangerous :-)
Andi Albrecht
this is an intersting discussion. I think that documenting the constructor of a class is necessary. Maybe as a special attribute of ClassDesc that refers to a MethodDesc for the __init__() method. This would allow templates a direct acces to the constructor method and they can render it wherever it seems to make sense. I can think of more than one solution where the constructor is displayed in the documentation: for example after the class name and before the docsting of the class. Or after the class docstring right before any members. Depending on the coding style the description for constructing a class may be found in the classes docstring or the docstring of the __init__() method. So template authors should have as much freedom as possible and I think that could be archived by a special class attribute for ClassDesc.
Andi
Daniel Haus
especially for the one who instanciates the class, so why not handle
it separately in the documentation? Looks to me like the best way to
deal with this issue.
Thank you, Andi and Gerdus, I'll try that!
Daniel Haus
I just implemented constructor support (in trunk, r52). Please tell
me, what you think!
Thanks for your ideas!
Am 08.03.2008 um 08:33 schrieb Andi Albrecht:
> Hi Daniel, hi Gerdus,
>
> this is an intersting discussion. I think that documenting the
> constructor of a class is necessary. Maybe as a special attribute of
> ClassDesc that refers to a MethodDesc for the __init__() method.
> This would allow templates a direct acces to the constructor method
> and they can render it wherever it seems to make sense. I can think
> of more than one solution where the constructor is displayed in the
> documentation: for example after the class name and before the
> docsting of the class. Or after the class docstring right before any
> members. Depending on the coding style the description for
> constructing a class may be found in the classes docstring or the
> docstring of the __init__() method. So template authors should have
> as much freedom as possible and I think that could be archived by a
> special class attribute for ClassDesc.
>
> Andi
--
Daniel Haus
http://ematia.de
Gerdus van Zyl
these fast feedback/ implementation times :-)
Now I just have to apply posterior to seat and finish documenting my
code in something resembling understandable engels. After I might have
more ideas, but for now I am happy.
~Gerdus
Andi Albrecht
But now I've got the same problem as Gerdus... Now that constructors show up in documentation, I have to document them... ;-)
Have a nice day,
Andi