i started with the implementation of the synchronization process. i think it should work, when i know the right source line. i just started with the implementation of this and the first tries look good.

some questions:
------------------------------

• do you know, how i can determine the source line with a regular expression? by now i have an array with the lines (a new funtion in 2.0). but when the method signature is on more then one line i have a little problem. any hints?
• how can you comment a enum member? it should possible, because in the html documentation every member is listed and it has a field with a description to every member. is there a special tag or something? i couldn't find out how i can do this.
• when do we make the meeting tomorrow? i would prefer 9pm swiss time.
  

vs project installation

a brief description of the installation of the new vs project (SharedCodeDoc2_0.sln):

• install visual studio 2005
• register the new framework to iis
• open console
• go to: C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727
• type in: aspnet_regiis -i
• wait until the installation procedure is finish
• start the vs project
• correct the path of the application home [PROJECT_LOCATION]\Presentation in Web.config
  
• make sure, that the presentation project is the startproject. startpage is the HomeForm.aspx.
  
• let's go .... (ctrl+f5) the application will run in the new built-in webserver.
• UPDATE: if you use firefox as your default browser, you must set in the Presentation property page the Start Option -> NTLM Authentication to false! if it's not already.
  
• if you want to run it, with the iis. make a new virtual directory, which points to the presentation folder of the vs project

UPDATE: all referenced assemblies are in the external dll folder of the project. for nunit you have to download the newest version (2.2.3)

screens screens screens

now i have the first official screens from the application:

home site

admin: project detail view

admin: new project

admin: modify project

the start page of the documentation

for tomorrows meeting i have no special topics from my site. only one or two question to the design or some implementation details. if you have any question or some input to the design. just write me an email.
by the way, today i solved the problem with the links and all works just fine. thanks to reto and remy for the input.

sync xml

i finished now the creation of the xml, which is the base to find the methods in the source files. it looks as follows:

<symbols file="C:\SharedCodeDocTestProjects\PdbTest\SharedCodeDoc.dll">
<files>
<file id="1" name="c:\SharedCodeDocTestProjects\CompilationTest\Class1.cs" />
<file id="2" name="c:\SharedCodeDocTestProjects\CompilationTest\Class2.cs" />
</files>
<metainfo>
<class name="CommentExample.CommentDelegate" />
<enum name="CommentExample.Color" />
<class name="CommentExample.Comments">
...
</class>
<enum name="CommentExample.Comments+CommentPriority" />
<struct name="CommentExample.Point">
<attribute name="x" type="Int32" file_ref="1" />
<constructor name=".ctor" file_ref="1">
<param>Int32</param>
</constructor>
</struct>
<class name="CommentExample.Comments2">
<attribute name="comment" type="String" file_ref="2" />
<attribute name="commentEvent" type="CommentDelegate" file_ref="2" />
<property name="Comment2" type="String" file_ref="2" />
<event name="commentEvent" type="CommentDelegate" file_ref="2" />
<constructor name=".ctor" file_ref="2" />
<constructor name=".ctor" file_ref="2">
<param>String</param>
</constructor>
<method name="get_Comment2" file_ref="2" />
<method name="set_Comment2" file_ref="2">
<param>String</param>
</method>
<method name="Main" file_ref="2">
<param>String[]</param>
</method>
<method name="UpperCase2" file_ref="2">
<param>Int32</param>
</method>
</class>
...
</metainfo>
</symbols>

i think it should be usable for the synchronisation. unfortunately it is not possible to print out the correct sourceline of the methods. the reader has a method, which should exactly do that. but unfortunately this method isn't implemented. but i have the correct method name. and can search after it.
i also changed the project from .net 1.1 to 2.0. i must replace the wilson master page with them from microsoft. because wilson master page didn't function correctly. when you try to execute the project. note that you first install the new .net version on the iis.
ok, that's all for the moment.

change to 2.0

it doesn't exist a version for mdbgcore.dll for the framework 1.1.
i found only a link, which describes the probs with version 1.1.
http://blogs.gotdotnet.com/jmstall/archive/2004/11/02/250946.aspx

it sounds very tough to implement it in version 1.1. i think it will take a lot of time to do this. and i haven't that time. so, what should we do? change to version 2.0?
i agree with reto, when the sharedcodedoc reaches a productive state, the mono project will have then fully integrated version 2.0.

Update:
Ok, reto and i have decided, that we advance to .net 2.0. because of the easier way to implement the synchronisation process. but i will not change the implementation of the existing code to 2.0. i will make a new vs project for 2.0 and leave the other on the svn.

synchronization problem

i took a look at the synchronization problem. i've tried to test the sample code from retos links. but i didn't it get running, because i couldn't find out, how i can reference the mscoree.dll from visual studio. in this dll is the IMetaDataDispenser defined. could you help me?

then i googled a little bit and found the following link:
http://blogs.msdn.com/jmstall/archive/2005/08/25/pdb2xml.aspx

in that link is an example, which generates a xml from the pdb file. and it works. see the xml below:

<symbols file="E:\Daten\HSR\diplomarbeit\SharedCodeDoc\bin\Core.dll">
<!--This is a list of all source files referred by the PDB.-->
<files>
<file id="1" name="E:\Daten\HSR\diplomarbeit\SharedCodeDoc\Core\CommentChangeLog.cs" />
<file id="2" name="E:\Daten\HSR\diplomarbeit\SharedCodeDoc\Core\HTMLEngine.cs" />
<file id="3" name="E:\Daten\HSR\diplomarbeit\SharedCodeDoc\Core\HTMLReader.cs" />
<file id="4" name="E:\Daten\HSR\diplomarbeit\SharedCodeDoc\Core\HTMLWriter.cs" />
<file id="5" name="E:\Daten\HSR\diplomarbeit\SharedCodeDoc\Core\ProjectManager.cs" />
<file id="6" name="E:\Daten\HSR\diplomarbeit\SharedCodeDoc\Core\ProjectSynchronizer.cs" />
<file id="7" name="E:\Daten\HSR\diplomarbeit\SharedCodeDoc\Core\Synchronizer.cs" />
</files>
<!--There is no entry point token such as a 'Main' method. This module is probably a '.dll'-->
<!--This is a list of all methods in the assembly that matches this PDB.-->
<!--For each method, we provide the sequence tables that map from IL offsets back to source.-->
<methods>
<method name="SharedCodeDoc.Core.Logging.CommentChangeLog.LogChangeComment" token="0x6000002">
<sequencepoints total="3">
</sequencepoints>
<locals>
<local name="CS$00000003$00000000" il_index="1" il_start="0" il_end="23" />
<local name="access" il_index="0" il_start="0" il_end="23" />
</locals>
</method>
<method name="SharedCodeDoc.Core.Logging.CommentChangeLog.LogChangeConflict" token="0x6000003">
<sequencepoints total="1">
<entry il_offset="0" start_row="25" start_column="3" end_row="25" end_column="4" file_ref="1" />
</sequencepoints>
<locals />
</method>
<method name="SharedCodeDoc.Core.Logging.CommentChangeLog.DeleteCommentChangeLog" token="0x6000004">
<sequencepoints total="1">
<entry il_offset="0" start_row="30" start_column="3" end_row="30" end_column="4" file_ref="1" />
</sequencepoints>
<locals />
</method>
...
</methods>
</symbols>

in this xml i have the reference from the method to the file. but now it comes the drawback! the code and some referenced assemblys are from .net 2.0. which i can't reference in .net 1.1. what should we do? change to 2.0? and hope that the mono project has as fast as possible integrated .net 2.0 or should i search for an other way to solve the problem?

edit comment sd

below you can see the sd for the edit comment process.
i hope, it helps a little bit to better understand the code.


if you have any questions. write me a mail.

ok, the edit comment process is emplemented now. i can now change the comment, the system can identify, that the comment has changed. the system log the comment change to the sharedcodedoc project specific xml file and writes the new html file to disk.
the comment changed xml file looks like this:

<ChangedComments>
<Namespace Name="CommentExample">
<Class Name="Comments">
<Method MethodSignature="publicstaticvoidMain(string[]str);" LastModified="20.11.2005 15:44:53">
<Comment>
<New>
<summary> summarytext Test</summary>
</New>
<Original>
<summary> summarytext </summary>
</Original>
</Comment>
<Comment>
<New>
<param name="str">paramtext Test</param>
</New>
<Original>
<param name="str">paramtext</param>
</Original>
</Comment>
<Comment>
<New>
<remarks>remarkstext Test</remarks>
</New>
<Original>
<remarks>remarkstext</remarks>
</Original>
</Comment>
<Comment>
<New>
<exception cref="">exceptiontext Test</exception>
</New>
<Original>
<exception cref="">exceptiontext</exception>
</Original>
</Comment>
<Comment>
<New>
<example>exampletext Test</example>
</New>
<Original>
<example>exampletext</example>
</Original>
</Comment>
<Comment>
...
</Comment>
</Method>
</Class>
</Namespace>
</ChangedComments>

i think these are all information, which i need for the sync process.

this is the agenda for the meeting tomorrow 5pm mez

• discussion link problem
• discussion control problem
• discussion synchronisation
• other problems
  
• next steps

you get more precisely information about the problems with the e-mail.

comment changelog

i started with the implementation of the documentation changelog today. it looks good, i think i could finish this tomorrow.
so we would have at monday the whole 'editcomment' process running. if the gui makes, what i will. i have a lot of problems with it. when the user presses the save button all controls from the page are gone. so i can't read the changes from the textboxes, which i added when the user has pressed the edit button. and therefore i can't track the documentation changes in the htmlwriter. i don't know where the mistake is. or what i should do. we can also look at this problem at monday. the only thing what i've tried is, that i save the controls in the cache from the site. i have then the controls when the user saves the documentation, but the text is the same as before editing :(

all right, i'll post the agenda for the weekly meeting tomorrow.

first screens !!!!

i made a good progress today.
i was able to solve the problem with the masterpages. i've made a user control, which is responsible for the documentation view (see the screens below). the system can now build the editpage with the textboxes (see the screens below). thats all what i made and tested today. i hope, that i can implement the save process of the documentation tomorrow.

these are the screens: (remark: the menu is only a prototype!)

the documentation page, which was generated with ndoc.

the editpage of the documentation above. (note: the text of requrements section is not that, it should be, because the xslt wasn't modify)

the link problem
--------------------------------
on the screens you can see a 'See also' section. in this section you can navigate to other documentation parts. the links, which are behind, are generated with ndoc. and these point now to a wrong location in the servers filesystem. when the user presses on such a link, i would track this. so i can correct the link and build the new page with the htmlengine. is that possible to implement? or do you have any other ideas?

little progress, lots of probs

the good news first. the parser can extract the comment text from the html source file. the HTMLSite class is able to determine, if the html contains editable comments. this is important for later implementation of the edit function. with this i can quickly decide if an edit button es required or not.
ok, after that i would start with the forms and then the problems came :-(
the actual problems:

• the links in the html source point to the wrong destination. but this can i fix. it has two possibilities to do that. first, i correct all the links with the parser. second, i intercept the every http request and rewrite the url if needed. but, how can i intercept the request? do i need a http module or a http handler for that? do you have any experiences with these? is that a good idea?
  
• the request interception do i need specially for the links which are defined in the generated documentation. because i can't define any events on these.
  
• i can show the html documentation in the browser. but it has some drawbacks with the masterpage. the documentation will be placed above all masterpage definition even if i define the control which shows the html text below the masterpage definition. do you have any hints or solutions?

parser

hi,

first, thanks to reto for the masterpage example. that helps me a lot.

i started with the parsing of the html pages. i think, i'll create a new class for that, which is responsible for the parsing proces. i'll put it in the same namespace, in which the other html classes are.
the parser will work that way:

1. search for the special tag
2. extract the documentation part
3. save the comment in the comment class

i have one thing, which i need your meanings about it. should i put the sharedcodedocproject class and the htmlsite to the data layer? because i build these data structures in the data layer and return them. now i have a circular dependency between the data and the core layer. what's your meaning?

it seems that it isn't a problem with the system assemblys references for the compilation. but i don't know, how it would be with own assemblys from the project. i'll test this in a later iteration.

i started today with the gui components. i've added for this reason a new class to the presentation layer. it calls BasePage. it is responsible for the basic features, which are on every page the same, like menu or later the layout of the sidebar.
below you can see the newest version of the class diagram.


for tomorrows meeting i have no special topics.
the agenda:

• information about the implementation progress
• questions, if any
• next steps
  

doc generation, source compilation

all right, today i implemented the generation of the documentation and the source code compilation. for the GetFiles method from the ProjectServerAccess class i made a temporary solution that gets the files from the same machine. i think for the first prototype it should be enough.
with the compilation i have one little problem. i can't find out, how i can specify the output path for the assembly. the rest runs properly. at the moment, the compiler saves the assembly in the same folder, in which the executing assembly locates. for the assembly i have a solution, which is a little hack. i can copy the assembly to that directory in which it should be. but it's a hack. have you any ideas, how i can specify the output path?

thats the code part, which makes the compilation:

// all files, which should compiled
string[] sourceFileNames = Directory.GetFiles(sourcePath, "*.cs");

// get csharp compiler
Microsoft.CSharp.CSharpCodeProvider provider = new Microsoft.CSharp.CSharpCodeProvider();
ICodeCompiler comp = provider.CreateCompiler();

// create compiler options
CompilerParameters compilerParam = new CompilerParameters();
compilerParam.CompilerOptions =
"/doc:SharedCodeDoc.xml /t:library";
compilerParam.OutputAssembly = "SharedCodeDoc.dll";


// compile it and pray ;-)
CompilerResults results = comp.CompileAssemblyFromFileBatch(compilerParam, sourceFileNames);

i hope i can start with the gui this weekend, so that we can see something ;-)

today i've started with the implementation.
i implemented today the ProjectPersistance class and it passed the tests that i made. i've tested it with the testdriven.net tool, which is a add-in for vs.net. when i run the same tests with nunit. they fail nearly all. i think nunit runs the tests in alphabetically order and not in the order the tests are written in the sourcefile. because for some test i need the datas from a previous test. should i fix that? and make the tests autonomous from the others?
for the compilation of the source files i added an interface ICompile in the data layer. i think thats a good solution, so we can add the compilation for other programming languages in later, later iterations simply. the class CSharpCompile implements this interface and is responsible for the compilation.

@reto:

• the Synchronizer class is the process, which starts the synchronization. the ProjectSynchronizer executes the sanchronization. i think, i should describe this in the design document.
  
• i don't understand what you mean with the renaming from Log to ChangeLog. for me the names are clear. can you make an example?
• your solution for the locking problem sounds good. thanks
• i'll correct the names in the sequence diagrams
  

design

thanks reto for your little example.
all right, today i've extended the dcd and the sequence diagrams.
the dcd isn't perfect now. but i think it's a good fundament to start with the implementation tomorrow. i've updated the sequence diagrams with the new methods and name from the dcd. please take a look at these atifacts below.

design class diagram

sd createsharedcodedocproject


sd edit comment


sd synchronizedocumentation

problem?
----------------------------

for the locking of the different documentation parts when a user starts editing, i haven't a good solution now. i thougt, that i make for each project a file, in which the documentation parts are saved, which are at this time locked. but i don't know, if this is a feasible solution? what are your thinkings about that?

design class diagram

i made today a first draft of the design class diagram. i know it doesn't look like that it should. because i didn't found out, how i can show the whole methode signature in together. i'll look tomorrow for an other tool. but i hope, you can see how i will implement the application.


a note to the dcd:

• i will make a data structure, that holds the information, which i'll return in a collection when the CommentHTMLReader searches for the editable comments. but i don't know, how i can show this in the diagram. because it's only for this. and it has no relation to any class.

please give me a hint, how i can solve this problem. also give me a feedback to the dcd draft.

srs and domain model approved

today we approved at the meeting the srs and the domain model.
we dsicussed also the sequence diagrams and the architecture draft. i'll extend the architecture tomorrow and then start with the class diagram. so that i can start with the implementation at Thursday.

today i took a look at the perspective wiki engine. but i think, it's not usable for our needs. because with a wiki engine, you can edit the whole page. but in our case, the user should be able to edit only a part of the page. i'll describe this in the design document, which i just created.

in the srs i refined the last use case. so i think we have now a solid srs, which we can work with.

first, thanks for your feedback to the srs.
i've made the additions to it.
i've one explanation to the srs. it concerns the uc06 edit documentation, i think how we make the unlocking process for a file when a user starts editing, but never finish it. is a design decision.

architecture
----------------------

i've made an architecture draft for tomorrows meeting.


i just send you the meeting materials for tomorrow.

here's the agenda again:

• approve srs
• discuss domain model
• discuss system architecture draft
• discuss sequence diagram draft
• next steps

the meeting starts at 5pm mez tomorrow.
i think we use this time skype for communication.

sequence diagrams

today i've made a first version of the sequence diagrams for the most important functions.

sd createsharedcodedocproject

sd editcomment

sd synchronizecomment

referenced sd ndoc from other sd's
shows only the part from ndoc

please give me a little feedback about these. then i can start with the class diagram tomorrow.
how about the srs? any comments?

hav a nice weekend

i've made some additions to the srs, which we have discussed yesterday. the srs is available on the server.

generating textboxes

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

also i took a closer at ndoc. and i found out, that i can format the html output my way. the html output is formatted by xslt. i can modify the xslt that way, that i can quick find the position in the html doc, which the user can edit. because each c# comment tag has it's own template in the xslt. in the xslt i can add an unique identifier, which i can quickly find when the user wants to edit the documentation, thus I know where the relevant text in the html is and I can insert the textboxes there.

an example:

source code documentation:

/// <summary>
/// Returns the comment ...
/// </summary>
/// <param name="length">The length</param>
/// <returns>The comment in upper case</returns>
public string UpperCase(int length)
{
return comment.ToUpper();
}

html doc with base xslt:

<div id="nstext">

<p> Returns the comment ... </p>

<div class="syntax">public <a href="ms-help://MS.NETFrameworkSDKv1.1/cpref/html/frlrfSystemStringClassTopic.htm">string</a> UpperCase(<br /> <a href="ms-help://MS.NETFrameworkSDKv1.1/cpref/html/frlrfSystemInt32ClassTopic.htm">int</a> <i>length</i><br />);</div>

<h4 class="dtH4">Parameters</h4>

<dl>

<dt>

<i>length</i>

</dt>

<dd>The length</dd>

</dl>

<h4 class="dtH4">Return Value</h4>

<p>The comment in upper case</p>

…

</div>

html doc with SharedCodeDoc xslt:

<div id="nstext">

<p id=”SharedCodeDoc_summarytext”> Returns the comment ... </p>

<div class="syntax">public <a href="ms-help://MS.NETFrameworkSDKv1.1/cpref/html/frlrfSystemStringClassTopic.htm">string</a> UpperCase(<br /> <a href="ms-help://MS.NETFrameworkSDKv1.1/cpref/html/frlrfSystemInt32ClassTopic.htm">int</a> <i>length</i><br />);</div>

<h4 class="dtH4">Parameters</h4>

<dl>

<dt>

<i><p id=”SharedCodeDoc_paramname”>length</p></i>

</dt>

<dd><p id=”SharedCodeDoc_paramtext”>The length</p></dd>

</dl>

<h4 class="dtH4">Return Value</h4>

<p id=”SharedCodeDoc_returntext>The comment in upper case</p>

…

</div>

wiki

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

I think it’s the best solution, when the system puts the new and old comment text in a xml-file. the html will also be updated, when the user presses the save button in the webinterface. when the system synchronizes the comments, it will use the xml-file. when we also save the old comment, we can compare the comment in the source file with the old command. this is important, when the ‘source code as master’ option is used. when the system has finished the synchronizing process, the xml-file will be removed if it’s empty. otherwise we have some conflicts, and the system sends the xml-file to the specified e mail address in the project settings.

srs finished

today i've finished the srs!!!

these are the new things in the srs:

• new use cases for project modification and removal
• specification for a administrator tool, the administrator tool is a win form gui
  

some screenshots:

this is the main form of the administrator tool. the administrator can here see all the sharedcodedoc projects, which are hosted on the server

this is the ui to add a project to the server.

and this is the final version of the domain model. i hope you understand this, although it has so much lines ;-)

some questions

first,
my today's progress:

• srs
• use cases added
• use case diagramm made
• screenshot in the appendix replaced
  
• domain model improved

explanations:
--------------------------

gui
on every page you have one edit button, with this you can edit all possible comments in this page.

problems:
--------------------------

• i have some problem with the use case for the 'sharedcodedoc project setup'. because i thougt so far, that the projects are on the same machine as the application is running. with the solution, which the projects are on the same machine it shouldn't be difficult to describe the process of project setup. but with the other one, it's very difficult. because we have the source files on two machines and the machines have no relationship to each other. tracking the changes and merging the documentation are very difficult. do you have any good ideas? or is that a problem up to the implementation of the source control feature? and i can accept, that the projects are on the same server?
  
• the solution, which we generate a base documentation sounds nice (thx to reto). but how often would you synch back the comments? how long should the period be? because you have then not at every time the newest source to document.
• for the conflict resultion problem, i have no idea, how we can fix this problem. i think we should make a skype conference tomorrow evening (swiss time) and discuss this. i think this is a major problem, that we should solve, before we start the implementation.
  

a lot of artifacts

these are the results of the last two days:

• refine the gantt-chart

• project plan:

• project responsibilities defined

• milestone artifacts, function-id added in the implementation phases

• system requirements specification:

• function description extended

• GUI specification added

• start with the external design

• first draft of the domain model

here are some impressions from the external design, the full external design can you find on the svn-server in the design folder.

this screenshot shows the first page, when you enter
the sharecodedoc site

the next one shows you a documentation page from a project.

the fields, which are marked with a red rectangle can be edited.

the comments from the previous screen will be filled in the textboxes. the user can edit the comment now.

domain model



gantt-chart

the revision of the gantt-chart, has changed the artifacts for next mondaysmeeting, because the srs takes more time then i expected. but i think it should be possible, that i can start with the implementation next week.



srs

i've identified the following use-cases:

• edit comment (Kommentar editieren)
• navigate throug documentation (Navigation)
• save documentation (Kommentar speichern)
• setup sharedcodedoc project (Projekt erstellen) -> new actor identified: server administrator

i think there are no more use cases, which are actors involved.


architecture

i think the best choice is, that we make a 2-tier architecture. the first tier contains all the presentation things and the second tier contains the core, which have the problem domain with documentation generation, read the documentation out of the source files and sync back the documentation into sourcefile. what are your thinkings about it?


if you have time, please give me a little comment specially for the srs and the use-cases. so that i can finish the srs tomorrow and start with the design process.