Source code documentation with coddocThe last email got muddled?

Simple typo - Copyright is spells wrong for one of the headings in that doc.
  "Juarez Rudsatz" <juarez@nowhere.com> wrote in message news:Xns9271CD52FD128juarezcorreiocom@63.105.9.61...
  Hi all!

      I am sending the second version of this especification.
      Is not concluded yet.
      Let's comment, criticize, speculate, think, talk ....

  Juarez Rudsatz

  Juarez Rudsatz <juarez@correio.com> wrote in
  news:Xns9249C9E0B98EEjuarezcom@63.105.9.61:

  > Hi all!
  >
  >          I am sending a very preliminary version of a specification
  >          for
  > implementing a sintax for document source files using the /* */
  > comments.
  >          It's a preliminary version and contain, certainly, design and
  > language errors.
  >          Please read the attached html file and send your comments.
  >



------------------------------------------------------------------------------


  Abstract
  A documentation model describes the format comments in the source code of a program must adhere to to be extractable by a documentation tool, which can then use the extracted information to create browsable or printable documentation, for instance in an html, pdf or word document format.

  This document is created with the purpose of specifying a clear and easy documentation model for the programming language D.

  Introduction
  Documentation comments are a method of reducing work by moving documentation from a separate document into the code itself in a way the documentation document could easily be generated. As every programmer knows, documentation tends to be incomplete, out of date, wrong, or non-existent. Moving the documentation into the code makes it easy to maintain with the program or library

  Tools for generating documentation of API's are commom today. They provide a simple method for programming and documenting at the same time. The documentation remains close to the source code for the API programmer, and for the application programmer will be in a more readable and easy to search format. They decrease the work of creating and maintaining documentation compared to writing it in a separate word processor. Most documentation generators will even be able to generate decent documentation from source code with no documentation comments in it at all, just from parsing the code itself. Adding good structured comments to the source code can greatly improve the value of the generated documentation however.

  How source code is documented
  Each feature of source code is composed by a set of language structures. For each structure is attached a comment providing a description of it functionality, a explaination of a component or classifying its atributes.

  See some examples below :

  A function being documented:
	/**
	 * This function is a simple example
	**/
	int function(int x) {
		return x;
	}

  A class being documented
	/**
	 * author: Wolfrang Amadeus Mozart <wam@music.org>
	 *
	 * This class plays a sinfonie of Mozart. It can be used for learning music
	 * or for learning D documentation
	**/
	class sinfonie{
	...
	}

  How tags are parsed
  Documented comments use a variation of the standart documentation for D. They starts with the string '/**´ and finish with the string '**´:

	/** This is a documented comment **/
	typedef int normalvalue;

  Alternatively a single line format can be used with the string '//*´:

	//* This is a documented comment
	typedef int normalvalue;

  To place a single line comment behind the source line, as is common, use '//<´:

      typedef int normalvalue; //< This is a documented comment

  The documentation can span several lines. The extra blanks, tabulation and new lines are stripped, just as with html:

	/**
	This comment will have
	many lines
	as needed
	**/

  If the documentation should be divided into more than one paragraph, you can add a blank line where you want to start a new paragraph:

	/**
	This is a paragraph

	And this is another
	**/

  To allow the comment style often used by programmers where every line in the comment block starts with an asterisk (*) aligned with the first asterisk in the start comment tag, the first asterisk of the comment lines are stripped if every comment line starts with an asterisk as the first non-whitespace character:

	/**
	 * This comment will have
	 * many lines
	 * as needed.
	 *
	 * And this is the second paragraph.
	**/

  Aditional repeated chars at begin or at end are omited:

	/***********************************
	 * The repeated chars are omited
	***********************************/

  The comment can have also a "tag" which specifies the documentation of an specific atribute:

	/**
	 * author: William Shakespeare <william@literature.net>
	**/
	module literature;

  The former tag specifies the author of the module. You can combine sereral tags and text in the comment:

	/**
	 * author: William Shakespeare <william@literature.net>
	 * version: 1.0
	 *
	 * This module implements the logic for understanding the real interpretation of my ideas.
	 * It magically translate all ideas hidden from the simple reading and show to you.
	**/
	module literature;

  Types of Tags
  The tags can be of two types :

    a.. Taglines are tags described in one line. The tag end at the newline caracter. As example there are the version, since, category and glossary tags.
    b.. Tag paragraphs are tages described in one or more lines. The tag end is at the next tag or the end of comment.
  Position of Tags
  Tags may be put before any declaration:

	/**
	 * author: William Shakespeare <william@literature.net> on 2002.03.04 05:06
	 * author: Wolfrang Amadeus Mozart <wam@music.org> on 2002.04.06 08:16
	 * version: 0.3 alpha
	 * category: Example of Code Documentation
	 * see: anotherexample, example, "D Programming Tutorial"
	 *
	 * This module is provided as example of documenting code with coddoc. It is
	 * a example of how use the coments for generating documentation.
	**/
	module docexample;

  It is also allowed to place documentation comments after the declaration using the special start tag ´//<´. These comments may only span one line however. Both forms may be mixed freely.

  This is an example of a struct with documentation comments:

	struct SDL_Color {
		Uint8 r;		//< The byte representing the red value for color
		Uint8 g;		//< The byte representing the green value for color
		Uint8 b;		//< The byte representing the blue value for color
		Uint8 unused;		//< This byte is reserved for future use
	}

  Especific tags
  Tag author
  The following are examples of author taglines, which may be used in documentation comments for module and types declarations:

	/**
	 * author: William Shakespeare<william@literature.net>
	 * author: Dante Aglieri
	 * author: Jules Verne
	**/
	module literature;

  Tag copyrigth
  The copyright tag may be used to describe the copyright holder information for the module, class or method
	/**
	 * copyright: Pavel "EvilOne" Minayev (c) 2001-2002
	 *
	 * This module provides a class library for windows programming.
	 * It contains controls necessary for creating windowed applications
	 * such as edit controls, list controls, menus, status bars and
	 * many other controls. It is also possible to derive your own
	 * custom controls.
	**/
	module wind;

  Tag license
  The following is an example of a license paragraph, which may be used in documentation comments for module declarations:

	/**
	 * license:
	 * Permission to use, copy, modify, distribute and sell this software
	 * and its documentation for any purpose is hereby granted without fee,
	 * provided that the above copyright notice appear in all copies and
	 * that both that copyright notice and this permission notice appear
	 * in supporting documentation.  Author makes no representations about
	 * the suitability of this software for any purpose. It is provided
	 * "as is" without express or implied warranty.
	**/

  The license paragraph should contain all information applicable to licensing terms and permission of use.

  Tag version
  The following is an example of a version tagline, which may be used in documentation comments for type declarations:

	/**
	 * version: 2.93.1 beta
	**/
	module imported;

  Tag since
  Specify in what version when the name was added to the API specification (if different from the implementation). It could be used in type in reference to module version or in method in reference to class version.

  The following is an example of a since paragraph, which may be used in documentation comments for declarations of methods:

	/**
	 * version: 0.3 alpha
	 *
	 * This class is on the third version
	**/
	class widgetfarm : farm {
		/**
		 * since: 0.2
		 *
		 * This method is introduced in version 0.2 of this class
		**/
		void initwidgets {
		 ...
		}
	}

  Tag see
  The following are examples of see paragraphs, which may be used in any documentation comment to indicate a cross-reference to a type, method, constructor, field, URL, or any text:

	/**
	 * see: c.stdio
	 * see: string
	 * see: string.equals
	 * see: threads.thread.wait(int)
	 * see: RandomAccessFile.RandomAccessFile(File)
	 * see: RandomAccessFile.RandomAccessFile(File, String)
	 * see: Character.MAX_RADIX
	 * see: "D Language Specification" at http://www.digitalmars.com/d/spec.html
	 * see: "D Programming Tutorial"
	**/
	class implementation;

  The character "." separates the name of a module of a class and the name of a class from the name of one of its fields, methods, or constructors. The order of searching is package, module, type, method. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method or constructor name.

  Tag category
  The category tagline specify in what category the type or method is gruped. It could be used in classes to classify the properties, methods and members in a closed scope.

  The following is an example of a category paragraph, which may be used in documentation comments for declarations of a functions:

	/**
	 * category: Temperature handling routines
	**/
	int temperature {
	...
	}

  Tag example
  Adds a example copied verbatim to documentation.

  The following is an example of a example paragraph, which may be used in documentation comments for providing user examples:

	/**
	 * example:
	 *
	 * // This ilustrate how to use a regexp to match a string
	 * RegExp myRegExp = new RegExp("[A-Za-z\b!]*");
	 * if (RegExp.Match("Hello World!")
	 *   printf("Hello World!");
	**/
	class RegExp
	{
	...
	}

  The formatting in the documentation remains exactly the same as it is in the source code. No whitespace is removed. A non-proportional font, such as courier is used for the examples, so simple ASCII drawings will survive the translation intact.

  Tag bug
  Specify known issue in types, methods or routines.

  The following is an example of a bug paragraph, which may be used in documentation comments for declarations of a functions:

	/**
	 * bug: Severity High. Windows 9x dont pass the correct memory used
	**/
	int memoryUsed {
	...
	}

  Tag todo
  Specify work to be done, such as implementing, optimizing or or documenting certain types and methods.

  The following is an example of a todo paragraph, which may be used in documentation comments for declarations of a class:

	/**
	 * version: 1.0
	 * todo: modify to permit evaluate a string caracter by caracter
	**/
	class RegExp
	{
	...
	}

  Tag glossary
  Specify a text to build a glossary by subject. The glossary tag is a tagline but a documentation comment may contain more than one glossary tag.

  The following is an example of a todo tagline, which may be used in documentation comments for declarations of a function:

	/**
	 * glossary: Deleting files
	 * glossary: Erasing files
	**/
	void delelefile(string filename){
	...
	}

  Tag summary
  The following is an example of an summary tagline, which may be used for short describing a artifact:

	/**
	 * summary: InterfaceDisconnect disconnects an IConnectionPoint interface.
	 *
	 * InterfaceDisconnect disconnects an IConnectionPoint interface connection
	 * that was previously made by the InterfaceConnect procedure.
	 * These procedures are wrappers for the ActiveX event-handling mechanism,
	 * the  IConnectionPointContainer and IConnectionPoint interfaces.
	**/
	void InterfaceDisconnect(IUnknown Source, ClassIID IID);

  Generic tags
  Tags for parameters
  The following are examples of parameters paragraphs, which may be used in documentation comments for method and constructor declarations:

	/**
	 * file: the file to be searched
	 * pattern: the pattern to be matched during the search. The pattern could
	 * consist of a simple string or a regular expression.
	 * count: the max number of lines to brings for each match. O for all lines;
	 *
	 * Matches lines in a file which follow a pattern.
	**/
	char[] matchLines(File file, char[] pattern, int count);

  The information in a parameter paragraph should consist of the name of the parameter followed by a short description.

  A documentation comment may contain more than one parameter tag. The usual convention is that if any parameter paragraphs are present in a documentation comment, then there should be one parameter paragraph for each parameter of the method or constructor, and the parameters paragraphs should appear in the order in which the parameters are declared but this is not mandatory.

  Tags for imports
  The following is an example of an import paragraph, which may be used in documentation comments for modules imports:

	/**
	 * Auxiliary routines
	**/
	import mymodule;

  The information in an import paragraph should consist of the name of an module (which may be a simple name or a qualified name) followed by a short description of the need or dependency reason.

  Additionaly, modules can be documented together simply by specifying the name of module contained in the colon list.

	/**
	 * mymodule: Auxiliary rotines
	 * c.stdio: needed for printf function
	 * stream: needed for reading and writing to files
	**/
	import mymodule, c.stdio, stream;

  Tags for exceptions
  The following is an example of an exception paragraph, which may be used in documentation comments for method and constructor declarations:

	void verifyWidget(Widget widget)
	{
		if (!widget.flanged)
			//* the widget does not have a flange, or its flange has size zero
			throw new UnflangedWidgetError(´Missing flange´);
		if (!widget.canUse)
			/**
			 * the widget cannot be used. This happens because it was not
			 * initialized, it was not attached to a manager, it was not
			 * configured or it is hided.
			**/
			throw new UnusableWidgetError();
		if (widget.InUse)
			throw new LockWidgetError("Widget is already in use"); //< the widget is already used
	}

  The comment in an exception paragraph is attached with the method which the error is throwed. For documenting the exception use a normal tag once a exception is a class.

  The information in an exception paragraph should consist by a short description of the circumstances that cause the exception to be thrown.

  Tags for return values
  The following is an example of an return paragraph, which may be used in documentation comments for method and functions declarations:

	byte cmpString(char[] str1, char[] str2)
	{
		if (str1 < str2)
			/** if the first string is smaller than second.
			 * return a positive number
			 */
			return 1;
		if (str1 == str2)
			//* if strings are equal return zero
			return = 0;
		if (str1 == str2)
			/** if the first string is greater than second.
			//* return a negative number
			return = -1;
	}

  Tags for Attributes
  Not all Attributes statements can be documented. There are no meaning in include documentation for the following tags:

    a.. private
    b.. protected
    c.. public
    d.. export
  Nevertheless the tool implementing documentation comments could include automatically the information and show or hide following user command.

  The following attributes can be commented:


    a.. deprecated
    b.. override
    c.. abstract
    d.. const
    e.. final
    f.. static
	/**
	 * As of D 2.0, replaced by stream handling methods
	 * see: stream
	**/
	deprecated
	{
		char[] read(File f)
		{
		...
		}

		int write(File f, char[] buffer)
		{
		..
		}
	}

  Tags for Contracts
  Contracts are a breakthrough technique to reduce the programming effort for large projects. Contracts are the concept of preconditions, postconditions, errors, and invariants. Contracts form part of the specification for a program, moving it from the documentation to the code itself.


  The comment in an assert contract is attached with the method which the contract is verified. For documenting the contract use a normal tag explaining the reason os such restriction. Assert contract without a documentation comment is not added in the documentation.

  Not all contracts can be documented. Following tags are not documented:

    a.. out contracts in methods
    b.. unittest contracts
  There are no meaning in include documentation for these contracts because they are commonly used for verification of accuracy of results and for determining if the code is working properly.

  The following contracts can be commented:


    a.. in contracts in methods
    b.. class invariants
  In Contracts
  The following is an example of documentation of an assert contract in a function in contract:

	int div(int x , int y)
	in
	{
		//* The divisor cannot be zero.
		assert(y != 0);
	}
	body
	{
		return x / y;
	}

  Class Invariants
  The following is an example of documentation of an assert contract in a class invariant:

	class Date
	{
	int day;
	int hour;

	invariant()
	{
		//* The day must be between 1 and 31
		assert(1 <= day && day <= 31);
		//* The hour must be between 0 and 23
		assert(0 <= hour && hour < 24);
	}

  Tags and versioning
  Tags will be included in documentation following the versioning scheme.

  Tags and inheritance
  Inherited classes and structs will inherit tags for all methods defined in ancestral which are not modified by an new documentation comment.

  Compilaton process
  The compiler will parse each file and generate a new file containing the comments stripped from source and all information about the feature being documented.

  The format of all files generated is the docboock format. Each source file generates one new file containing a section in a docbook book. The document must be also a valid XML 1.0 document.

  Users could use a docbook processor for generate documentation in html format, text format, pdf format or any available format.

  Users can also write their own preprocessor since the output of code documentation will be a simple xml document.


  Sugested comments for statements
  Tags in simple types
  Tags in simple procedures
  Tags in functions
  Tags in structures
  Tags in classes
  Best practices
  A Style Guide
  The following are useful tips and conventions for writing descriptions in doc comments.

  When specifying data use formal and standard notation
  When specifying data such as dates and times use accepted standards such as ISO. This way foreign readers will not be confused by month, day positions.

	module greataddon;  //< should be ready 2002.12.31 00:00:00.

  Omit parentheses for the general form of methods and constructors
  When referring to a method or constructor that has multiple forms, and you mean to refer to a specific form, use parentheses and argument types. For example, ArrayList has two add methods: add(Object) and add(int, Object).

	The add(int, Object) method adds an item at a specified position in this arraylist.

  However, if referring to both forms of the method, omit the parentheses altogether. It is misleading to include empty parentheses, because that would imply a particular form of the method. The intent here is to distinguish the general method from any of its particular forms. Include the word "method" to distinguish it as a method and not a field.

	The add method enables you to insert items.			(preferred)
	The add() method enables you to insert items.		(avoid when you mean "all forms" of the add method)

  Okay to use phrases instead of complete sentences
  In the interests of brevity this could be used. This holds especially in the initial summary and in parameter tag descriptions.

  Use 3rd person (descriptive) not 2nd person (prescriptive).
  The description is in 3rd person declarative rather than 2nd person imperative.


	Gets the label.			(preferred)
	Get the label.			(avoid)

  Method descriptions begin with a verb phrase.
  A method implements an operation, so it usually starts with a verb phrase.

	Gets the label of this button.					(preferred)
	This method gets the label of this button.		(avoid)

  Class/interface/field descriptions can omit the subject.
  they can simply state the object. These API often describe things rather than actions or behaviors:

	A button label.						(preferred)
	This field is a button label.		(avoid)

  Use "this" instead of "the"
  When referring to an object created from the current class is preferred use a more specific word. For example, the description of the getToolkit method should read as follows:

	Gets the toolkit for this component.		(preferred)
	Gets the toolkit for the component.			(avoid)

  Add description beyond the API name.
  The best API names are "self-documenting", meaning they tell you basically what the API does. If the doc comment merely repeats the API name in sentence form, it is not providing more information. For example, if method description uses only the words that appear in the method name, then it is adding nothing at all to what you could infer. The ideal comment goes beyond those words and should always reward you with some bit of information that was not immediately obvious from the API name.

  The description below says nothing beyond what you know from reading the method name. The words "set", "tool", "tip", and "text" are simply repeated in a sentence. It's better avoid this form of documentate.

	/**
	 * Sets the tool tip text.
	 *
	 * text:  The text of the tool tip.
	**/
	public void setToolTipText(String text);

  This description more completely defines what a tool tip is, in the larger context of registering and being displayed in response to the cursor. This form is preferred in comparison with the first.

	/**
	 * Registers the text to display in a tool tip.   The text
	 * displays when the cursor lingers over the component.
	 *
	 * text:  The string to display.  If the text is null,
	 * the tool tip is turned off for this component.
	 */
	public void setToolTipText(String text);

  Be clear when using the term common term.

  Be aware that the common word as "field" can have many meanings and can confuse the reader.


  Avoid Latin
  Use "also known as" instead of "aka", use "that is" or "to be specific" instead of "i.e.", use "for example" instead of "e.g.", and use "in other words" or "namely" instead of "viz."

"anderson" <anderson@firestar.com.au> wrote in news:ak2i1a$1agt$1@digitaldaemon.com:

> Source code documentation with coddocThe last email got muddled?

Sorry, I am not a native english speaker. I have not understood what you writed. Can you explain please ?

A new update in code documentation syntax. I think this have evolved much
since the first version. But need more discution until reach a solid stage.
Maybe it is time of balancing the costs against the benefits.
Please take a look at the specification and send your comments, preferences
and questions. This is a not so prioritary project, but it could bring good
advantages for the language by having a start in this direction.

Saudações

Juarez Rudsatz

Juarez Rudsatz <juarez@correio.com> wrote in news:Xns9249C9E0B98EEjuarezcom@63.105.9.61:

> Hi all!
> 
>          I am sending a very preliminary version of a specification
>          for
> implementing a sintax for document source files using the /* */
> comments.
>          It's a preliminary version and contain, certainly, design and
> language errors.
>          Please read the attached html file and send your comments.
> 

Nested numbered lists will have a problem with the following:

#1 Top list, item 1
#2 Top list, item 2
#1 Nest list, item 1
#2 Nest list, item 2
#3 Which list?, item 3

If indentation is a controlling mechanism, it needs to be documented as such. You'll also need to document whether whitespace or tabs are to be used, how translations between whitespace and tabs will be performed (some editors do auto-indentation to align with previous lines, which can cause followup lines to use spaces when the original line used tabs:

#1 Top list, item 1
#2 Top list, item 2
<tab>#1 Nest list, item 1
<sp><sp><sp><sp>#2 Nest list, item 2
#3 Which list?, item 3

It might be better to take the list ending blank line and also use it for sublists:

#1 Top list, item 1
#2 Top list, item 2
#1 Nest list, item 1
#2 Nest list, item 2

#3 Top list, item 3

Of course, this just delays the inevitable:

#1 Top list, item 1
#2 Top list, item 2
#1 Nest list, item 1
#2 Nest list, item 2
#1 Deep list, item 1
#2 Deep list, item 2

#3 Which list?, item 3

Two blank lines in a row (the direct extension of my previous suggestion) is not
particularly obvious when you read it.  It may be necessary to make a
terminating symbol to end a (sub)list:

#1 Top list, item 1
#2 Top list, item 2
#1 Nest list, item 1
#2 Nest list, item 2
#x
#3 Top list, item 3
#x

Or some such...

Mac
In article <Xns927FC90E25C36juarezcom@63.105.9.61>, Juarez Rudsatz says...
>
>A new update in code documentation syntax. I think this have evolved much
>since the first version. But need more discution until reach a solid stage.
>Maybe it is time of balancing the costs against the benefits.
>Please take a look at the specification and send your comments, preferences
>and questions. This is a not so prioritary project, but it could bring good
>advantages for the language by having a start in this direction.
>
>Saudações
>
>Juarez Rudsatz
>
>Juarez Rudsatz <juarez@correio.com> wrote in news:Xns9249C9E0B98EEjuarezcom@63.105.9.61:
>
>> Hi all!
>> 
>>          I am sending a very preliminary version of a specification
>>          for
>> implementing a sintax for document source files using the /* */
>> comments.
>>          It's a preliminary version and contain, certainly, design and
>> language errors.
>>          Please read the attached html file and send your comments.
>> 

"Juarez Rudsatz" <juarez@nowhere.com> wrote in message news:Xns927FC90E25C36juarezcom@63.105.9.61...
> A new update in code documentation syntax. I think this have evolved much
> since the first version. But need more discution until reach a solid stage.
> Maybe it is time of balancing the costs against the benefits.
> Please take a look at the specification and send your comments, preferences
> and questions. This is a not so prioritary project, but it could bring good
> advantages for the language by having a start in this direction.
> 
> Saudações
> 
> Juarez Rudsatz


Looking great. This docGen thing will add value to D.

My suggestion,

Parhaps there could be a way to modularise the docGen, so that files that don't change don't need to be re-worked with doc gen. That may not need to be in the documentation though. Also it would be nice if users could specify a webpage where the latest docgen document resides. That way local versions could remain current.

ie
/*
 * web version: www.something.com/Documents/
*/

Parhaps this could be done with see, however I think it could be neetly formated into the headers(or footer) of the page.

The above may produce something like (for the car page):

Find the latest of this webpage

Note that the docgen would point directly to the wepage www.something.com/Documents/Car.html, and web version is just in generic form. The class rocket ship under www.something.com/Documents/ would point to (www.something.com/Documents/Rocket Ship.html)

Of course theres the possiblily of bad links, like when the webpage\class structure changes. In these cases a default docgen page could also be created to capture these errors.

It would be nice if the docgen produced pages into separt folders depending on the package which they reside, optionally or a zip file. That's more a docgen compiler thing then a spec thing.

Joel Anderson

PS -
copyrigth ?? -> copyright

Juarez Rudsatz wrote:
> A new update in code documentation syntax. I think this have evolved much since the first version. But need more discution until reach a solid stage.
> Maybe it is time of balancing the costs against the benefits.
> Please take a look at the specification and send your comments, preferences and questions. This is a not so prioritary project, but it could bring good advantages for the language by having a start in this direction.
> 

I quickly scanned through the document and a couple of things did stand
out to me (I'll do a more thorough read later).

<quote>

Alternatively a single line format can be used with the string '///´:

  /// This is a documented comment
  typedef int normalvalue;

</quote>

Can we use single line comments in place of the /** **/ style comments,
as shown below:


  ///
  /// author: Wolfrang Amadeus Mozart <wam@music.org>
  ///
  /// This class plays a sinfonie of Mozart. It can be used for learning
  /// music or for learning D documentation
  ///
  class sinfonie{
  ...
  }



<quote>

To place a single line comment behind the source line, as is common, use
'///<´:

  typedef int normalvalue; ///< This is a documented comment

</quote>


Just wondering... but why use ///< and not simply /// like the single
line comments above?

Jason

Jason Mills wrote:

> To place a single line comment behind the source line, as is common, use
> '///<´:
> 
>   typedef int normalvalue; ///< This is a documented comment
> 
> </quote>
> 
> 
> Just wondering... but why use ///< and not simply /// like the single
> line comments above?

So that the doc generator knows which line is commented (next or previous). It's doxygen syntax.

"anderson" <anderson@firestar.com.au> wrote in news:al7dgi$2nua$1@digitaldaemon.com:

> Parhaps there could be a way to modularise the docGen, so that files that don't change don't need to be re-worked with doc gen. That may not need to be in the documentation though

I have thinked in make :


SOURCES = $(wilcard *.d)    	# get all files with extension d in this dir
CHAPTERS = $(.d:.dch)    	# replace the extension .d by .dch

$(CHAPERS) : $(SOURCES)    	# generate each chapter from source file
    	coddoc $^        	    	# compile using coddoc

"anderson" <anderson@firestar.com.au> wrote in news:al7dgi$2nua$1@digitaldaemon.com:

> Also it would be nice if users could specify a webpage where the latest docgen document resides. That way local versions could remain current.
> 
> ie
> /*
>  * web version: www.something.com/Documents/
> */
> 
> Parhaps this could be done with see, however I think it could be neetly formated into the headers(or footer) of the page.
> 
> The above may produce something like (for the car page):
> 
> Find the latest of this webpage
> 
> Note that the docgen would point directly to the wepage www.something.com/Documents/Car.html, and web version is just in generic form. The class rocket ship under www.something.com/Documents/ would point to (www.something.com/Documents/Rocket Ship.html)
> 
> Of course theres the possiblily of bad links, like when the webpage\class structure changes. In these cases a default docgen page could also be created to capture these errors.
> 

What about two alternatives :

1. The user can include in the module source file:

/**
 * see: "D Language Specification" at
http://www.digitalmars.com/d/spec.html
 **/
import foo;

and the compiler can detect the url and generate a html like:

<p>
  <b>See Also:</b>"D Language Specification" at <a
href="http://www.digitalmars.com/d/spec.html">
http://www.digitalmars.com/d/spec.html</a>

But this is a quality of implementation issue.

2. The user can include a hand generated docbook chapter with references or another instruction and compile and generate the html, pdf, tex, text or what he want.