[Mono-list] Re: [Mono-docs-list] WebControls Documentation

[John Knipper]

>     Personally speaking, I am not in favour of
> inline-comments. At times, I
I am not in favor of exclusively external comments, I don't want to
have to lookup the documentation in external files each time I'm reading my
(or others) code.

> myself get confused with my comments (if too long). Let there
for longer comments you could use a tag like in vs.net to include external
files:

<include file='filename' path='tagpath[@name="id"]' />

For me, the code comments should be a short and easy to read information. I
find it handy
to be able to read in the source comments what each parameter is and does. A
short statement
is enough.

> by when we can do things... we can start off documentation
> externally and if
> acceptable at a later stage, can embed it with the source.
I find this also not to be a good approach... It will be a pain to integrate
the documentation
at a later stage because if you do it at first you will not have to do it
later. Also the
code might no longer be synchronised with the documentation when you want to
integrate it back, etc...

I suggest that the basic documentation, should be put directly in the code.
The tags I find necessary
are <summary>, <author>, <param name=">, <return>, <exception> and <value>
for short things like properties.
The comments found in the code should be in english. If we choose only to
use english as comments in the code, then there is no need to specify that
it's english.

> : What if we added XML documentation comments to the class
> library source : files in English, let csc (or mcs) generate the XML
> documentation file, and then use that as a starting point to translate
into other languages?
>
>     Back to square one - I think, this is what we have been
> trying to avoid.
Why is this something we should avoid ? I find this is the right choice to
do...
the problem here is what happens when the code is updated...getting the
initial english documentation
is easy but the synchronising that file with the translated counterparts
will be a pain...
But you can see that the XML files generated by the compiler looks like
- <member
name="M:Accor.Web.UI.WebControls.PanelDataGrid.OnOKNewItem(System.Object,Sys
tem.EventArgs)">
  <summary>Called by the 'save' button in the footer</summary>
  <remarks>used in InFormularEdit mode only</remarks>
  <param name="Src" />
  <param name="e" />
  </member>
What we would need here is a tool that uses the member name property (that
uniquely identify a piece of comment)
to inject the documentation in a database. that way you would have a table
with the following structure:
|membername|original english doc|other languages 1| other languages 2|
etc...
M:Accor.Web.UI.WebControls.PanelDataGrid.OnOKNewItem(System.Object,System.Ev
entArgs)|<summary>Called by the 'save' button in the footer</summary>
  <remarks>used in InFormularEdit mode only</remarks>
  <param name="Src" />
  <param name="e" />|<summary>Appelé par le boutton de save dans le pied de
page</summary>
  <remarks>Seulement utilisé dans le mode formulaire</remarks>
  <param name="Src" />
  <param name="e" />|etc...

That way we can easily inject documentation changes to the database,
translate the code, and build all the documentation translation using the DB
and the XMl generated documentation...
This is what I will push on our projects here, and when time permits I will
have to build the tools I'm talking
about...

John.