Compiler documentation & documentation comments
andrey....@gmail.com
1) I wanted to generate Nemerle assemblies documentation from the
sources and found trunk\misc\Nemerle.ndoc.xml that (I presumed) is
supposed to perform this task for me.
However it refers to some files (<assembly
location="../ncc/out.stage3/Nemerle.dll"
documentation="../ncc/Nemerle.xml" />
<assembly location="../ncc/out.stage3/Nemerle.Compiler.dll"
documentation="../ncc/Nemerle.Compiler.xml" />
<assembly location="../ncc/out.stage3/Nemerle.Macros.dll"
documentation="../ncc/Nemerle.Macros.xml" />)
that haven't been created during the normal compiler build (using
"MSBuild Nemerle.sln").
So the question is how to make it work? Is it Linux build specific?
2) When I looked through compiler sources I noticed marked comments
(/** */).
Sometimes they contain XML tags (but usually no <summary>). Does this
mean that Nemerle doc comments are supposed to be similar to XML
comments in C# style (e.g. <param name='name'>description</param>)?
Is compiler's "-doc" switch fully functional at the moment?
What about alternative Javadoc/doxygen style comments (e.g. \param name
description)?
(sometimes XML seems to be an overkill especially when you're without
Intellisense :-) ).
Michal Moskal
>
> Hello!
Hi!
>
> 1) I wanted to generate Nemerle assemblies documentation from the
> sources and found trunk\misc\Nemerle.ndoc.xml that (I presumed) is
> supposed to perform this task for me.
> However it refers to some files (<assembly
> location="../ncc/out.stage3/Nemerle.dll"
> documentation="../ncc/Nemerle.xml" />
> <assembly location="../ncc/out.stage3/Nemerle.Compiler.dll"
> documentation="../ncc/Nemerle.Compiler.xml" />
> <assembly location="../ncc/out.stage3/Nemerle.Macros.dll"
> documentation="../ncc/Nemerle.Macros.xml" />)
> that haven't been created during the normal compiler build (using
> "MSBuild Nemerle.sln").
> So the question is how to make it work? Is it Linux build specific?
No. It should be posssible to make MSBuild generate them. You just
need to pass -doc: option to ncc.
>
> 2) When I looked through compiler sources I noticed marked comments
> (/** */).
> Sometimes they contain XML tags (but usually no <summary>). Does this
> mean that Nemerle doc comments are supposed to be similar to XML
> comments in C# style (e.g. <param name='name'>description</param>)?
> Is compiler's "-doc" switch fully functional at the moment?
We had an idea, that the first paragraph of the comment would be
treated as summary and the rest as the description. I.e. instead of
having explicit <summary> and <description> and <p> tags, to have some
convention. It wasn't fully implemented, it shouldn't be hard to do.
Marcin Młotkowski developed a program to translate this XML to HTML,
that could be used instead of NDoc (I guess it's better to have
nemerle-specific tool here -- we want special display for certain
types, variants and so on). The effects can be seen at:
http://www.ii.uni.wroc.pl/~marcinm/ndp/
He promised to make the source code public (under Nemerle-like
license) by the end of the week.
>
> What about alternative Javadoc/doxygen style comments (e.g. \param name
> description)?
> (sometimes XML seems to be an overkill especially when you're without
> Intellisense :-) ).
This is why we don't have this <summary> thing. As for <param> maybe
at least </> as closing tag could be used? It seems that just nobody
got arround to implement this stuff.
--
Michał
Michal Moskal
> Marcin Młotkowski developed a program to translate this XML to HTML,
> that could be used instead of NDoc (I guess it's better to have
> nemerle-specific tool here -- we want special display for certain
> types, variants and so on). The effects can be seen at:
>
> http://www.ii.uni.wroc.pl/~marcinm/ndp/
>
> He promised to make the source code public (under Nemerle-like
> license) by the end of the week.
The same URL now contains also the source code.
--
Michał
Andrey Khropov
It didn't even compile but I fixed it.
Maybe it should be placed in "trunk\tools" to facilitate development?
I also modified "*.nproj" files to ensure MSBuild-based build generates
documentation files.
Kamil Skalski
> Maybe it should be placed in "trunk\tools" to facilitate development?
This would be cool to integrate it into project. Michal, you need to
convince Marcin M. to become official contributor of the project :)
>
> I also modified "*.nproj" files to ensure MSBuild-based build generates
> documentation files.
Probably it should go as separate task, because AFAIR the
implementation of -doc causes a bit of slowdown of compilation.
--
Kamil Skalski
http://nazgul.omega.pl
Michal Moskal
>
> >
> > Maybe it should be placed in "trunk\tools" to facilitate development?
>
> This would be cool to integrate it into project. Michal, you need to
> convince Marcin M. to become official contributor of the project :)
Done. I've just commited the sources.
--
Michał