* Gerhard Killesreiter <killesreiter@xxxxxxxxxxxxxxxxxxxxxx> [2004-06-16 12:46]:
> On Wed, 16 Jun 2004, Todd Grimason wrote:
> > * Gerhard Killesreiter <killesreiter@xxxxxxxxxxxxxxxxxxxxxx> [2004-06-16
> > 06:07]:
> a) It is a bit difficult to document "invent a module"
> b) the code contains an increaing amount of doxygen comments.
First off, thanks again for continuing this discussion. I don't mean to
harass, just trying to get it all straight.
a) Well of course I didn't mean to document the "invent" part - more so the
implementation. For example, just explaining the innards of any
already-existing, well done module(a new node type ideally) would be a huge
help. The sample module (Diary) only uses default node fields so it doesn't
answer the "how do I add a _____ field to my module" question. [I do notice
the "see recipe.module" line now - though that reference is the 'download
the zip and open and read the source type of reference'.]
It could be really really short and sweet too - the (already written) code
illustrates everything - the "docs" would be along the lines of "here we
need to save a field not defined in the base node.module so we do X: [code
snippet]".
b) It is definitely improving, no disagreement. This is great.
> > You say to write a module. Previously I read the node_api doxygen docs which
> > say:
> >
> > "If you don't need to make a new node type but rather extend the existing
> > ones, you should instead investigate using hook_nodeapi()."
>
> There you go.
> > and
> >
> > "If you are writing a node module, do not use this hook to perform actions
> > on your type of node alone. Instead, use the hooks set aside for node
> > modules, such as hook_insert() and hook_form()."
>
> Yep.
>
> > <http://drupal.kollm.org/tmp/drupal-phpdoc/>
> >
> > These two points are far from clear.
>
> Not to me. If you have a better formulation I'd like to hear it.
If I had a better one I wouldn't be asking all these questions! <g>
But in general I think the issue is this - yes the localized docs and
comments are decent - what's lacking for me, and others based on the FAQs on
the lists, is a (clear) higher-level conceptual overview. I'd guess this
contributes to the many comments floating around the web that drupal is not
"friendly" (the app not the people).
By that I mean how the different approaches relate to each other - when one
needs to create an entire new node module, or when the only thing that needs to
be done is implement some node_api hooks, and so forth.
OK -- writing this out has made clearer (to me) the reason I'm confused
(clear confusion?). One of the most confusing aspects of the core code is
the (to me) apparent lack of distinction between "content type" modules, and
more functional modules(those that primarily act on other content types).
The treatment of everything as a node -- I realize this in many ways gives
drupal its flexibility and power(and is legacy), but it vastly complicates
the process of "getting" how the whole thing works.
A clear overview of this distinction is again I think the best way to
improve this.
I think since I'm coming from more of a OOP background, the procedural style
of much of the core hides the big picture to me somewhat. As (a
OOP-brainwashed person) I'd argue describing things in more real-world terms
would help newcomers understand things;
Here's how I'm starting to map the translation in my head:
- Node is the base class that all content types (would/should) extend
- Plug-ins (non-content-based modules) act on content types, using the
node_api which is analagous to callbacks, or eventhandlers. For example, a
"NodeManager" would call, on an update:
editNode.update() # followed by broadcasting
foreach plugin in plugins:
plugin.handleEvent(EV_NODE_UPDATE, editNode)
wherein any plugin not interested in an UPDATE event would ignore the call,
those with handlers for it would do their thing. If your plugin added a form
field in EV_NODE_RENDERFORM, it would know to grab that field and
validate/save it.
Is this basically what node_api is/does?
> We sure would like to have better docs, if they are unclear. But we also
> can't write a whole novel in doxygen comments.
Agreed, my "lack of comments in code" comment was more appropriate for
contributed modules, I should have qualified it better. The doxygen docs are
in fact quite good (now that you've directed me to the right places).
I think the key missing ingredient is a short (up to date) conceptual
overview. With a solid understanding of the basic idea(s), the importance of
specific examples and copius comments is drastically reduced.
If my OOP-speak understanding above is correct, or close, I'd be happy to
give a shot at writing up such an overview - of course I'd need those who
already grok all this to make sure I'm explaining things correctly...
--
____________________________
toddgrimason*tag@xxxxxxxxxxx
--
[ Drupal support list | http://list.drupal.org/ ]
|
