openerp-expert-framework team mailing list archive

[Albert Cervera i Areny <albert@xxxxxxxxxxx>]

A Dissabte, 12 de desembre de 2009, Simone Orsi va escriure:
> > For example, in the "res.partner.vat" case one would see:
> > 
> > """
> > Description: Value Added Tax number. Check the box if the partner is
> > subjected  to the VAT. Used by the VAT legal statement
> > 
> > References:
> > 
> > * .... The invoicing process won't work unless partner's vat field has a 
> > correct value. ....
> > """
> 
> I don't think it'd be a good idea to place extra info for fields into
> the docs. Fields have to be documented in the code.
> 

So what's documentation for then? I'm just saying that given that in the 
documentation there are references to specific fields, why not make those 
references available from the field itself? I think current field help 
information is just great and should be kept. I'm just proposing to improve 
that.

Take this as an example. This text is extracted from [1]:
"""
a specific or a default payment condition can be defined for this partner in 
the Sales & Purchases area of the partner form. Payment conditions are 
generated by rules for the payment of the invoice. For example: 50% in 21 days 
and 50% in 60 days from the end of the month.
"""

As you can see this fragment is extracted from the invoicing chapter but 
refers to a field in the partner. With the proposed documentation system, the 
documentation writer would do something like this:

"""
a specific or a default <field name="partner.payment_term_id">payment 
condition</field> can be defined for this partner in the Sales & Purchases 
area of the partner form. Payment conditions are generated by rules for the 
payment of the invoice. For example: 50% in 21 days and 50% in 60 days from 
the end of the month.
"""

Then, the documentation generator would convert that to some preconfigured 
tags. Say:

"""
a specific or a default <i>payment condition</i> can be defined for this 
partner in the Sales & Purchases area of the partner form. Payment conditions 
are generated by rules for the payment of the invoice. For example: 50% in 21 
days and 50% in 60 days from the end of the month.
"""

And add the cross reference to the corresponding table for the given field. Of 
course, these preconfigured tags could be improved so that from within this 
documentation is also possible to see the generic help of the field (the one 
in the help="" parameter we add to fields in python).


[1] http://doc.openerp.com/book/3/3_7/invoicing.html#entering-a-customer-
invoice

-- 
Albert Cervera i Areny
http://www.NaN-tic.com
Mòbil: +34 669 40 40 18