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

[Gaurav Vaish]

Right,
    This has been the crux of the problem since start of the documentation.

    Personally speaking, I am not in favour of inline-comments. At times, I
myself get confused with my comments (if too long). Let there be only and only
external documentation, not even of the things like summary, remarks or param
options.

    So, how do you propose to start us now? I mean, it pains to see time passing
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.

    For the time being, Joe - volunteering to help me out in documentation, can
start off external docs. btw, he is quite insterested in putting up sample
examples for the methods / properties - that will be really nice.

Cheers,
Gaurav Vaish
http://home.iitk.ac.in/student/gvaish
http://calendar.yahoo.com/mastergaurav
---------------------------------


----- Original Message -----
From: "Piers Haken" <piersh@friskit.com>
To: "Miguel de Icaza" <miguel@ximian.com>
Cc: <mono-list@ximian.com>; <mono-docs-list@ximian.com>
Sent: Friday, March 08, 2002 13:57
Subject: RE: [Mono-list] Re: [Mono-docs-list] WebControls Documentation


: indeed, i hadn't thought about the multiple language issue. but surely
: the problem remains: in most cases the docs are going to be written in
: english first and then translated (unless the doc writers are fluent in
: 27 languages -- apollogies, of course, to those non
: english-as-1st-language speakers amogst us <ahem>). It might make sense
: to have the english version of the docs embedded in the code and then
: have separeate 'translation' files that could easily be written in XSLT
: to generate the corresponsing docs for different languages.
:
: For example:
:
: <xsl:tempate match="/doc/assembly [name="corlib"]/members/member
: [@name="M:Object.GetHashCode"/summary>
: <summary>C'est le plus foobar method du tout.</summary>
: </xsl:template>
:
: (Please excuse my French!)
:
: The matching xpath query could probably me much simpler than this if the
: documentation were limited to a specific .xsl file per .cs file.
:
: You could have all the docs in Object_<locale>.xsl and have some pretty
: simple tools to automatically check which bits for each language are
: missing from each code file. Hey, and maybe display a nice tree of what
: still needs to be done ;-)
:
: I just think that if you really want people to write docs while they're
: writing code then the best place to put it is right there, in their
: faces.
:
: There's no excuse that it takes up too much room in the file: two of my
: editors can automatically colapse them: can yours?
:
: #regions would be nice...
:
: Piers.
:
:
:
:
: -----Original Message-----
: From: Miguel de Icaza [mailto:miguel@ximian.com]
: Sent: Thursday, March 07, 2002 4:58 PM
: To: Piers Haken
: Cc: mono-list@ximian.com; mono-docs-list@ximian.com
: Subject: RE: [Mono-list] Re: [Mono-docs-list] WebControls Documentation
:
:
: Oops.
:
:   I sent that email without finishing.
:
:   Anyways, having 27-languages embedded in your source code, like this:
:
: /// <summary lang="en">
:   ///   Returns the Name of this type
: /// </summary>
: /// <remarks lang="en">
: ///   The type must be non-null, and you should make sure that
: ///   the frobber has been properly initialized
: /// </remarks>
: /// <summary lang="es">
: ///   Regresa el nombre de este tipo.
: /// </summary>
: /// <remarks lang="es>
: ///   El tipo debe de tener un valor no-nulo, y el usuario debe
: ///   de asegurarse que el frobber ha sido propiamente
: ///   inicializado.
: /// </remarks>
:
: public string Name {
: get {
: return value;
: }
: }
:
:    Those were two languages, now add 25 more.
:
:    I suggested to keep only english in the source code, and having the
: translations in external files, but people who routinely maintain
: translations of APIs complained heavily because this is a very hard way
: of tracking documentation changes.  It was because of their experience
: that we have decided to place the documentation externally.
:
:     We could use the Microsoft XML DTD for the documentation, I have no
: problem with this.  I am not sure if the documentation tools that John
: outlined and that were later maintained by Adam are finished or complete
: for this task, but we should find out.
:
: Miguel.
:
: _______________________________________________
: Mono-list maillist  -  Mono-list@ximian.com
: http://lists.ximian.com/mailman/listinfo/mono-list