Vista - Powershell inline documentation feature ?

I was wondering if powershell offers some kind of inline documentation
as does VB.NET and C# that can later be extracted and used with tools
like NDoc ?

Powershell documentation in xml format and can be easy extracted, just type
get-help
and
get-help *
to see it.

Look at http://del.icio.us/powershell/Help for some examples.

--
Gusev Vasily, AKA Xaegr
MCP, MCSA
http://xaegr.livejournal.com
<apanospam57@hotmail.com> wrote in message
news:rd4qr2dbo7bhgt6rcsh874l7d3r5o34ml2@4ax.com...
>I was wondering if powershell offers some kind of inline documentation
> as does VB.NET and C# that can later be extracted and used with tools
> like NDoc ?

If you mean does PowerShell have a similar ability to that in C# to use

/// some text here

and then extract it later into xml or html then no it does not.

It is possible to exttract information from a cmdlet that you have writtent
to populate a PowerShell xml based help file - see Get-CmdletMaml from the
PowerShell Comunity Extensions

http://www.codeplex.com/Wiki/View.as...e=PowerShellCX

Otherwise you can create an about_topic.help.txt file, put it in the
PowerShell install folder and access it via get-help about_topic

--
Richard Siddaway

Please note that all scripts are supplied "as is" and with no warranty


"apanospam57@hotmail.com" wrote:

> I was wondering if powershell offers some kind of inline documentation
> as does VB.NET and C# that can later be extracted and used with tools
> like NDoc ?
>

On Mon, 29 Jan 2007 02:37:14 -0800, RichS
<RichS@discussions.microsoft.com> wrote:

>If you mean does PowerShell have a similar ability to that in C# to use
>
>/// some text here
>
>and then extract it later into xml or html then no it does not.
>
>It is possible to exttract information from a cmdlet that you have writtent
>to populate a PowerShell xml based help file - see Get-CmdletMaml from the
>PowerShell Comunity Extensions
>
>http://www.codeplex.com/Wiki/View.as...e=PowerShellCX
>
>Otherwise you can create an about_topic.help.txt file, put it in the
>PowerShell install folder and access it via get-help about_topic


Well that's exactly what I was hoping not only for cmdlet's but also
for plain simple *.ps1 files. Since I'm planing to make our batch jobs
in PS and include inline documentation that could be extracted and
used to feed an intranet website for a simple and low effort
documenation of the whole system.

anyway thanks very much for the feedback

Thinking about it you might be able to mimic the behaviour. If you used

#/// some comment

in the file and then used

PS> get-content test.ps1 | select-string "///"

#/// some text
#/// some more text

you can extract the data. You could use out-file to push it into a file for
later processing
--
Richard Siddaway

Please note that all scripts are supplied "as is" and with no warranty


"apanospam57@hotmail.com" wrote:

> On Mon, 29 Jan 2007 02:37:14 -0800, RichS
> <RichS@discussions.microsoft.com> wrote:
>
> >If you mean does PowerShell have a similar ability to that in C# to use
> >
> >/// some text here
> >
> >and then extract it later into xml or html then no it does not.
> >
> >It is possible to exttract information from a cmdlet that you have writtent
> >to populate a PowerShell xml based help file - see Get-CmdletMaml from the
> >PowerShell Comunity Extensions
> >
> >http://www.codeplex.com/Wiki/View.as...e=PowerShellCX
> >
> >Otherwise you can create an about_topic.help.txt file, put it in the
> >PowerShell install folder and access it via get-help about_topic
>
>
> Well that's exactly what I was hoping not only for cmdlet's but also
> for plain simple *.ps1 files. Since I'm planing to make our batch jobs
> in PS and include inline documentation that could be extracted and
> used to feed an intranet website for a simple and low effort
> documenation of the whole system.
>
> anyway thanks very much for the feedback
>

I asked for same thing during the beta process. Did not really get any joy
as no priority at the time. Maybe next version. I think it would be a
great feature. You could keep your documentation dynamic and up-to-date
right from the source (if you keep the source doc in sync).

--
William Stacey [C# MVP]
PCR concurrency library: www.codeplex.com/pcr

<apanospam57@hotmail.com> wrote in message
news:e3psr2pncr7uf478tvu4j2110k8t90hl0o@4ax.com...
| On Mon, 29 Jan 2007 02:37:14 -0800, RichS
| <RichS@discussions.microsoft.com> wrote:
|
| >If you mean does PowerShell have a similar ability to that in C# to use
| >
| >/// some text here
| >
| >and then extract it later into xml or html then no it does not.
| >
| >It is possible to exttract information from a cmdlet that you have
writtent
| >to populate a PowerShell xml based help file - see Get-CmdletMaml from
the
| >PowerShell Comunity Extensions
| >
| >http://www.codeplex.com/Wiki/View.as...e=PowerShellCX
| >
| >Otherwise you can create an about_topic.help.txt file, put it in the
| >PowerShell install folder and access it via get-help about_topic
|
|
| Well that's exactly what I was hoping not only for cmdlet's but also
| for plain simple *.ps1 files. Since I'm planing to make our batch jobs
| in PS and include inline documentation that could be extracted and
| used to feed an intranet website for a simple and low effort
| documenation of the whole system.
|
| anyway thanks very much for the feedback

On Mon, 29 Jan 2007 21:30:46 -0500, "William Stacey [C# MVP]"
<william.stacey@gmail.com> wrote:

>I asked for same thing during the beta process. Did not really get any joy
>as no priority at the time. Maybe next version. I think it would be a
>great feature. You could keep your documentation dynamic and up-to-date
>right from the source (if you keep the source doc in sync).


William, I'm absolutely on the same line here, documentation away from
code is dead documentation. That's exactly why I'm looking for it.


This one is a good start:

PS> get-content test.ps1 | select-string "///"

#/// some text
#/// some more text

however I'm now stuck when I try to remove the #/// in the same line
of code. Is this possible ? It seems I have a MatchInfo object at that
time and this one doesn't like to be trimmed

There is probably a faster 1 liner, but this seems to work.

PS C:\> gc test.ps1 | %{ if ($_.startswith("#///")) {
$_.replace("#///","").trim() } }

--
William Stacey [C# MVP]
PCR concurrency library: www.codeplex.com/pcr
PSH Scripts Project www.codeplex.com/psobject


<apanospam57@hotmail.com> wrote in message
news:mii1s2ph2a51s1p373aqght0dp7j8jolqc@4ax.com...
| On Mon, 29 Jan 2007 21:30:46 -0500, "William Stacey [C# MVP]"
| <william.stacey@gmail.com> wrote:
|
| >I asked for same thing during the beta process. Did not really get any
joy
| >as no priority at the time. Maybe next version. I think it would be a
| >great feature. You could keep your documentation dynamic and up-to-date
| >right from the source (if you keep the source doc in sync).
|
|
| William, I'm absolutely on the same line here, documentation away from
| code is dead documentation. That's exactly why I'm looking for it.
|
|
| This one is a good start:
|
| PS> get-content test.ps1 | select-string "///"
|
| #/// some text
| #/// some more text
|
| however I'm now stuck when I try to remove the #/// in the same line
| of code. Is this possible ? It seems I have a MatchInfo object at that
| time and this one doesn't like to be trimmed
|
|