Feedback: Documentation update
I'd like to propose a slight tweak to the documentation that would improve understanding for future me. At https://doc.metalama.net/api/metalama_framework_code_syntaxbuilders_statementfactory the Parse(String) method "indicates that the parsed string can be inserted into the run-time code using InsertStatement(IStatement)." I would recommend this be updated to include an example of where one might find the InsertStatement, as in: "using InsertStatement(IStatement) as in
meta.InsertStatement(IStatement) as the linked documentation also doesn't mention that this method is available on meta. Only on the "related" link at the bottom of this subsequent page does it link to "Writing T# Templates" and then on "Generating run-time code" do we fine a note of "To add a statement to the generated code, use StatementBuilder to create the statement and then meta.InsertStatement from the template at the place where the statement should be inserted`.
By including this note on the StatementFactory and StatementBuilder pages, it would make it easier to understand how it might be implemented (especially if in the docs generated and bundled with the package on NuGet).18 Replies
Thank you for the feedback.
I don't see how we could implement from a technological point of view because embedded examples in XML doc are cumbersome to write and cannot be unit-tested. We can add examples in the compiled documentation (the one in doc.metalama.net), but this would not appear in the IDE. At the moment, I don't see a practical way to improve the in-IDE doc at scale, considering that this API is just one in a thousand.
How could we achieve this?
This is indeed something of a catch 22 and there is no perfect solution.
In the vast majority of cases api's that have been properly commented (my tool of choice for this is Atomineer which is pretty much untouchable in this field) will provide enough information.
However there are always exceptions to this and in those cases the addition of example code in the comments that gets carried through to the documentation can be very beneficial.
Yes that comes at the cost of no unit testing, but in the main that is a relatively small price to pay for better clarity and explanation.
For me, at this point, this is a question of policy. We have to find a policy that works and scale. I wonder if having the working hyperlinks from the IDE would help. There could be two hyperlinks from the specific API of the current example: one to https://doc.metalama.net/api/metalama_framework_code_syntaxbuilders_statementfactory exactly and one to the "see also". I'm fine with a policy of linking more APIs to their conceptual documentation.
I can see the sense in having a policy because, apart form anything else it brings with it consistency. In that respect I have no problem with links from the api to the conceptual documentation.
However, api's are to a certain extent meant to be self documenting and the minute that you start adding links that don't derive directly from them you leave yourself open to missing things as you have to actively edit the api documentation in the first place to provide those links.
The harsh reality is that there is no right or wrong answer to this. With that in mind I would suggest that perhaps you try the following.
Pick one aspect (you'll have to pardon the pun here) of Metalama that is not the easiest the of thing to follow and create potential documentation along both (or more if applicable) of your chosen documentary paths and throw it open to wider discussion.
The best analogy that I can come up with for this conundrum are DIY manuals. Typically the problem that you have at the time you decide to consult said manuals never quite exactly matches the examples that are provided. The more experienced you are the easier it becomes to interpret what you read and apply it to the circumstance in which you find yourself, and of course by extension the less experienced you are the harder it is to understand what is being described.
I'll poke around other libraries I've enjoyed the documentation of and see if I can't figure out what sort of policy they take.
The one example I usually turn to that is in my view documentation done well is that produced by Dev Express (https://docs.devexpress.com). The vast majority of the actual API documentation is pretty dry, sometimes linking out to examples on GitHub, but every now and then you'll find a section of the api doc goes deeper, usually in those area where the need to understand a topic is vital. Here a good example from their wpf docs (https://docs.devexpress.com/WPF/DevExpress.Mvvm.UI.EventToCommand).
Note also two other key points. The documentation is grouped (selectively for the end user) into targeted Framework and the version of the actual controls you're interested in.
DevExpress.Mvvm.UI Namespace | WPF Controls | DevExpress Documentation
Developer documentation for all DevExpress products.
Do you know if they have this extra doc inside the IDE or just in the online doc?
It's not in the IDE itself, essentially intellisense is limited to display <Summary>, <Remarks> <Params> and <Exceptions> by default to prevent overload.
In this particular case this is additional stuff that gets added after the initial autodocumention of the api has taken place.
In some respects DX are both a good, and bad example to pick. Good, because it's an excellent demonstration of what good well thought out documentation both looks like and can achieve. Bad, because DX have actually created their own markdown parser for the vast majority of what they produce.
If examples are not in the Intellisense doc then the initial problem boils down to discoverability of the online documentation from the IDE.
We also have Markdown extensions btw https://github.com/postsharp/Metalama.Documentation/tree/master/code/Metalama.Documentation.DfmExtensions
GitHub
Metalama.Documentation/code/Metalama.Documentation.DfmExtensions at...
Documentation of Metalama aspect framework. Contribute to postsharp/Metalama.Documentation development by creating an account on GitHub.
That can be done quite easily.
Create a simple console app in VS and add the following code to it:
///---- BuildAspect (Method) ----
///
/// <summary>
/// Builds an aspect.
/// </summary>
///
/// <remarks> You can find out more <see href="https://vtlsoftware.co.uk"></see> </remarks>
///
/// <param name="builder">The builder.</param>
///
/// <seealso cref="M:Metalama.Framework.Aspects.OverrideMethodAspect.BuildAspect(IAspectBuilder{IMethod})"/>
///-------------------------------------------------------------------------------------------------
public override void BuildAspect(IAspectBuilder<IMethod> builder)
{
if(!(builder.Target.Attributes.OfAttributeType(typeof(DoNotLogMethodAttribute)).Any() ||
builder.Target.Attributes.OfAttributeType(typeof(TimedLogMethodAttribute)).Any()))
{
builder.Advice.Override(builder.Target, nameof(this.OverrideMethod));
}
}
However the cursor over BuildAspect and you will see that the remark appears along with the clickable hyperlink. You just have to learn to work with what will be pulled into intellisense by default.
It would be easy enough to generate while building the nuget packages
Indeed it would, moreover, were you to use a tool like Atomineer to generate the in editor xml comments documentation itself, and if you take the time to set up the vast array of possible customisations that it supports you could pretty much achieve this without actually having to physically write anything at all.
Realistically there will always be the need for some editing but I never cease to be amazed at what can be achieved with some applied forethought to the customisation.
Maybe the Metalama extension could override the F1 key (see https://stackoverflow.com/a/13943702/41071), so that pressing it would open Metalama Docs instead of a useless MSDN page? Though I don't know how well-known F1 help is in VS.
Stack Overflow
Visual Studio intercepting F1 help command
Im looking to write a visual studio addin that can intercept the default online help command and grab the MSDN library URL when F1 help is called on a class or type.
For example say I place my cur...
Given that the original premise of the discussion was centred around providing additional information and potentially examples as well about some aspects of Metalama whose implementation might not be obvious on first glance and equally given the fact that it does, to a certain extent make sense to try and make that additional information more accessible from the ide (and preferably actually in intellisense itself) I think invoking F1 would actually be a retrograde step.
That's just a personal opinion though.
That's just a personal opinion though.
I remember hitting F1 in the 90s
I remember accidentally hitting F1 last week and waiting for the tab to open so I could promptly close it 🙂
GitHub
Add links to online doc to xml doc · postsharp Metalama · Discussio...
Make it easier to go from the XML doc, from the IDE, to the online doc.